Copyright © ${copyright.year} ${project.organization.name}. All rights reserved.

Online version published by ${project.organization.name}, ${organization.address}.

Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries.

Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries.

IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries.

Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries.

Apache and the Apache feather logo are trademarks of The Apache Software Foundation.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and ${project.organization.name} was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Foreword: ${project.version}

This book covers both Nexus Open Source and Nexus Professional, a product which brings full control and visibility to organizations which depend on Maven repositories to manage releases and distribute software. You are encouraged to check http://books.sonatype.com/nexus-book weekly for any updates to the content.

If you would like to receive updates whenever there is a change to this book, you can subscribe to our Book Announcement mailing list. To subscribe to this mailing list, send an email to: book-notify-subscribe@sonatype.org

We welcome your feedback, please do not hesitate to contact the Sonatype team with any questions or ideas you may have about the product. We’re focused on making the adoption of Nexus Open Source and Nexus Professional painless, and we are here to do anything we can to help speed up the learning curve associated with some of the more advanced and powerful features of Nexus.

If you have any feedback or questions, you are encouraged to post an item in our Get Satisfaction page for this book: http://www.getsatisfaction.com/sonatype/products/sonatype_repository_management_with_nexus

Tim O’Brien, Sonatype

${release.month}, ${copyright.year}

Edition: ${project.version}

Changes in Edition 3.0.1

The following changes were made in 3.0.1:

  • Added New Section <xref linkend="using-dependencies" />. (NXBOOK-577)

  • Added a step about setting to LANG to the post-install checklist. (NXBOOK-561)

  • Updated template for new Sonatype web site.

Changes in Edition 3.0

The following changes were made in 3.0:

  • Added Anders Hammar as an author. (NXBOOK-577)

  • Upgrade Nexus version number fo 1.9.0.2. (NXBOOK-580)

  • Removed a section that was focused on providing upgrade instructions for users upgrading from Nexus 1.5 to Nexus 1.6. (NXBOOK-578)

  • Transitioned image generation tools from Photoshop-based Macros to a series of scripts using Imagemagick to scale and create book images. (NXBOOK-579 and NXBOOK-581)

  • Updated Sonatype’s address to Maryland address. (NXBOOK-565)

  • Fixed a minor typo in <xref linkend="installation-sect-upgrading" />. (NXBOOK-499)

  • Removed instructions for upgrading Nexus 1.2 to Nexus 1.3 from <xref linkend="installation-sect-upgrading" />. (NXBOOK-583)

The following people helped improve the quality of Edition 3.0 by reporting typos, making suggestions, or contributing directly to the development of this book:

  • Trevor Harmon for reporting typos in NXBOOK-499.

Introducing Sonatype Nexus

Introduction

Nexus manages software “artifacts” required for development, deployment, and provisioning. If you develop software, Nexus can help you share those artifacts with other developers and end-users. Maven’s central repository has always served as a great convenience for users of Maven, but it has always been recommended to maintain your own repositories to ensure stability within your organization. Nexus greatly simplifies the maintenance of your own internal repositories and access to external repositories. With Nexus you can completely control access to, and deployment of, every artifact in your organization from a single location.

Nexus Open Source

Nexus Open Source provides you with an essential level of control over the external Maven repositories you use and the internal repositories you create. It provides infrastructure and services for organizations that use repository managers to obtain and deliver software. If you create software libraries or applications for your end-users, you can use Nexus Open Source to distribute your software. If your software depends upon open source software components, you can cache software artifacts from remote repositories.

Nexus Open Source Features

Hosting Repositories

When you host a Maven repository with Nexus Open Source, you can upload artifacts using the Nexus interface, or you can deploy artifacts to hosted repositories using Maven. Nexus will also create the standard Nexus Index for all of your hosted repositories which will allow tools like m2eclipse to rapidly locate software artifacts for your developers.

Proxy Remote Repositories

When you proxy a remote repository with Nexus Open source you can control all aspects of the connection to a remote repository including security parameters, HTTP proxy settings. You can configure which mirrors Nexus will download artifacts from, and you can control how long Nexus will store artifacts and how it will expire artifacts which are no longer referenced by your build.

Repository Groups

Grouping repositories allows you to consolidate multiple repositories into a single URL. This makes configuring your development environment very easy. All of your developers can point to a single repository group URL, and if anyone ever needs a custom remote repository added to the group, you can do this in a central location without having to modify every developer’s workstation.

Fine-grained Security Model

Nexus Open Source ships with a very capable and customizable security model. Every operation in Nexus is associated with a privilege, and privileges can be combined into standard Nexus roles. Users can then be assigned both individual privileges and roles that can be applied globally or at a fine grained level. You can create custom administrative roles that limit certain repository actions such as deployment to specific groups of developers and you can use these security roles to model the structure of your organization.

Flexible LDAP Integration

If your organization uses an LDAP server, Nexus Professional can integrate with an external authentication and access control system. Nexus Professional is smart enough to be able to automatically map LDAP groups to the appropriate Nexus roles, and it also provides a very flexible facility for mapping existing users and existing roles to Nexus roles.

Artifact Search

Nexus Open Source provides an intuitive search feature which allows you to search for software artifacts by identifiers such as groupId, artifactId, version, classifier, and packaging, names of classes contained in Java archives, keywords, and artifact checksums. Nexus search makes use of the industry standard for repository indexes, the Nexus Index format, and Nexus will automatically download a Nexus index from all remote repositories which create a Nexus index. Nexus will also automatically expose a Nexus index for any hosted repositories you create.

Scheduled Tasks

Nexus Open Source has the concept of scheduled tasks

  • periodic jobs which take care of various repository management tasks such as deleting old snapshots, evicting unused items, and publishing repository indexes.

REST Services

Nexus Open Source is based on a series of REST services, and when you are using the Nexus web front-end UI, you are really just interacting with a set of REST service. Because of this open architecture, you can leverage the REST service to create custom interactions or to automate repository management with your own scripts.

Nexus Plugins

Nexus Open Source provides a rich API for extension in the form of Nexus Plugins. When you write a Nexus Plugin, you can customize REST services, the Nexus UI, repository formats, or write components that can intercept requests and add new capabilities to the platform. The plugin API which you have access to in Nexus Open Source is the same plugin API that is used to implement value-added features available in Nexus Professional.

Integration with m2eclipse

When you use Nexus as a repository manager it creates indexes that support some of the next-generation tools available in m2eclipse - Sonatype’s Maven plugin for the Eclipse IDE. If you publish new artifacts and archetypes to Nexus, they are immediately available to m2eclipse project creation wizards and are included in m2eclipse search results.

Nexus Open Source License

Nexus Open Source is available under the GNU Affero General Public License version 3 (AGPLv3). The text of this license is available from the Open Source Initiative (OSI) here: http://opensource.org/licenses/agpl-v3.html

The Nexus Indexer is made available under the Eclipse Public License -v 1.0. The text of this license is available from the Open Source Initiative (OSI) here: http://www.opensource.org/licenses/eclipse-1.0.php

Nexus Professional

Nexus Professional was designed to meet the needs of the enterprise. It is a central point of access to external repositories which provides the necessary controls to make sure that only approved artifacts enter into your software development environment. It is also a central distribution point with the intelligence required to support the decision that go into making quality software. The extensibility provided by the custom metadata plugin coupled with REST services only available in Nexus Professional also lay the foundation for highly complex interactions within the enterprise. Once you start to use the workflow and decision support features of Nexus Professional, you will start to see it as the “assembly line” - the central collaboration point for your software development efforts.

Nexus Professional Features

Nexus Procurement Suite

Consider the default behavior of a proxy repository. Any developer can reference any artifact stored in a remote repository and cause Nexus to retrieve the artifact from the remote repository and serve back to a developer. Very often a company might want to control the set of artifacts which can be referenced in a proxy repository. Maybe the company has unique security requirements which require every third-party library to be subjected to a rigorous security audit before they can used. Or, maybe another company has a legal team which needs to verify that every artifact referenced by your software adheres to an inflexible set of license guidelines. The Nexus Procurement Suite was design to give organization this level of control over the artifacts that can be served from Nexus.

Nexus Staging Suite

When was the last time you did a software release to a production system? Did it involve a QA team that had to sign-off on a particular build? What was the process you used to redeploy a new build if QA found a problem with the system at the last minute? Because few organizations use a mature process to manage binary software artifacts, there is little in the way of infrastructure designed to keep track of the output of a build. The Nexus Staging Suite changes this by provide workflow support for binary software artifacts. If you need to create a release artifact and deploy it to a hosted repository, you can use the Staging Suite to post a collection of related, staged artifacts which can be tested, promoted, or discarded as a unit. Nexus keeps track of the individuals that are involved in a staged, managed release and can be used to support the decisions that go into producing quality software.

Hosting Project Web Sites

Nexus Professional is a publishing destination for project web sites. While you very easily generate a project web site with Maven, without Nexus, you will need to set up a WebDAV server and configure both your web server and build with the appropriate security credentials. With Nexus, you can deploy your project’s web site to the same infrastructure that hosts the project’s build output. This single destination for binaries and documentation helps to minimize the number of moving parts in your development environment. You don’t have to worry about configuring another web server or configuring your builds to distribute the project site using a different protocol, you simple point your project at Nexus and deploy the project site.

Support for OSGi Repositories

Instead of just supporting Maven repositories, Nexus Professional supports OSGi Bundle repositories and P2 repositories for those developers who are targetting OSGi or the Eclipse platform. Just like you can proxy, host, and group Maven repositories, Nexus Professional allows you to do the same with OSGi repositories.

Enterprise LDAP Support

Nexus Professional offers LDAP support features for enterprise LDAP deployments including detailed configuration of cache parameters, support for multiple LDAP servers and backup mirrors, the ability to test user logins, support for common user/group mapping templates, and the ability to support more than one schema across multiple servers.

Support for Atlassian Crowd

If your organization uses Atlassian Crowd, Nexus Professional can delegate authentication and access control to a Crowd server and map Crowd groups to the appropriate Nexus roles.

The User Account Plugin

When you are running a large, public instance of Nexus, it is often very useful to allow users to sign up for an account without the assistance of an administrator. Nexus Professional’s User Account plugin allows for just this. With this plugin activate, a new user simply has to fill out a simple form and type in letters from a CAPTCHA. Once a user has signed up for Nexus, Nexus will then send an email with a validation link. If you are working in an environment with hundreds or thousand of users the user account plugin will allow you to support the tool without having to create logins for each individual user.

Maven Settings Management

Nexus Professional along with the Nexus Maven Plugin allow you to manage Maven Settings. Once you have developed a Maven Settings template, developers can then connect to Nexus Professional using the Nexus Maven plugin which will take repsonsibility for downloading a Maven Settings file from Nexus and replacing the existing Maven Settings on a local workstation.

Support for Artifact Bundles

When software is deployed to the Maven Central repository, it is deployed as a signed artifact bundle. Nexus Professional’s Staging Suite allows you to upload artifact bundles to a staged repository.

Artifact Validation and Verification

The software artifacts you download from a remote repository are often signed with PGP signatures. Nexus Professional will make sure that these PGP signature are valid and the procurement plugin defines a few other rules that can be applied to artifacts which are downloaded from remote repositories. Nexus Professional also defines an API which allows you to create your own custom verification rules.

Custom Repository Metadata

Nexus Professional provides a facility for user-defined, custom metadata. If you need to keep track of custom attributes to support approval workflow or to associate custom identifiers with software artifacts, you can use Nexus to define and manipulate custom attributes which can be associated with artifacts in a Nexus repository.

Nexus Professional License

Nexus Professional is made available under a commercial license for businesses. Is available for free for use in qualifying Open Source projects, and is available at a discount for select Non-profits.

Choosing a Nexus Edition

If you are wondering which edition is appropriate for your organization. The following sections outline some reasons for choosing either Nexus Open Source of Nexus Professional.

Use Nexus Open Source…

…if you are new to Repository Management

If you are new to repository management, you should pick up a copy of Nexus Open Source, and experiment with Hosted and Proxy repositories. You should get a sense of how Maven Settings are configured to retrieve artifacts from a single Repository Group, and you should download a copy of the free Nexus book - Repository Management with Nexus. Once you’ve familiarized yourself with Nexus Open Souce, you can easily upgrade to Nexus Professional by downloading and installing Nexus Professional. Nexus stores all of your repository data and configuration in a directory named sonatype-work which is separate from the Nexus application directory.

…if you are looking for more stability and control

If you depend directly on public repositories such as the Maven Central repository or the various repositories maintained by organizations like Codehaus or the Apache Software Foundation, you rely on these servers to be available to your developers 100% of the time. If a public repository goes down for maintenance, so does your development process. With a local proxy of Maven artifacts, you buy yourself a stable, isolated build. Even if a public repositories becomes unavailable, you will still be able to build your software against artifacts cached in your own Nexus installation.

…if you need to manage internal software distribution

If your organization needs to support collaboration between internal teams, you can use Nexus to support the distribution of internal software. With Nexus, sharing components between internal groups is as easy as adding a dependency from Maven Central. Just publish a JAR to Nexus, configure the appropriate repositories groups and inform others in our organization of the Maven coordinates. Using a repository management doesn’t just make it easier to proxy external software artifacts, it makes it easier to share internal artifacts.

…if you need an intelligent local proxy

Many developers run Nexus on a local workstation as a way to gain more control over the repositories used by Nexus. This is also a great way to start evaluating Nexus. Download and install Nexus on your local workstation and point your Maven settings at http://localhost:8081/nexus. When you need to add a new repository, all you need to do is change the configuration of your local Nexus installation.

…if you need to integrate with an LDAP server

If you need to integrate Nexus with an an LDAP server, download Nexus Open Source. Nexus provides documented integration with popular LDAP servers such as OpenLDAP, Microsoft’s Active Directory Server, and any other directory product which implements the LDAP standard.

Use Nexus Professional…

…if you are looking for Professional Support

When you purchase Nexus Professional, you are purchasing one year of support from the team that created the industry-standard in repository management. With Nexus Professional, you not only get a capable repository manager, you get the peace of mind that help is just a phone call away. Sonatype also offers an array of implementation and migration services for organizations looking for an extra level of assistance. Contact Sonatype Sales for more information, call +1 (888) 866-2836.

…if you need a repository manager that can support release and quality assurance decisions:: Nexus Professional’s Staging Suite can track the staatus of a software release and make sure that different decision makers are notified and supported during a software release. If you are looking for a repository manager that can automate and support software releases, download Nexus Professional and start learning about Staged repositories and Staging Rulesets. When you start using Nexus Professional, your operations, quality assurance, and development teams can use the repository manager as a central point of collaboration.

…if you need more control over external artifacts

If you need more control over which external artifacts can be referenced and used in internal projects, you will need to use the Nexus Procurement Suite which is a part of Nexus Professional. While repositories like Maven Central are a great convenience, allowing your developers carte blanche access to any external library is often unacceptable in today’s legal and regulatory environment. Nexus Professional’s Procurement Suite allows you to enforce standards for external libraries. If you want to ensure that every dependency is evalautated for security or license compliance, download Nexus Professional.

…if you develop software for an Open Source project

Are you developing an open source project? If so, most open source projects qualify for a free Nexus Professional license. Open source projects can qualify for a free Professional license, or they can take advantage of free Nexus Professional hosting on http://oss.sonatype.org. Sonatype is very committed to supporting the development of quality open source and this is our way of giving back to the community.

…if you are developing and deploying to OSGi platforms

If you are developing OSGi components using OBR repositories, or if you are developing OSGi components using the P2 repository format, you will need to use the OSGi support available in the Nexus Professional distribution. Nexus Professional supports a wider array of repository formats than Nexus Open Source. As the industry moves toward OSGi as a standard, you should be using a product which supports these emerging standards as well as the existing repository formats used by millions of developers.

…if you need to integrate with Enterprise-level Security (LDAP and Crowd):: If you need to integrate Nexus with an Atlassian Crowd server or an enterprise LDAP deployment involving multiple servers or multiple LDAP schemas, download Nexus Professional. While Nexus Open Source provides extension points for writing custom security realms, Nexus Professional provides solid LDAP and Crowd support for the large, mission-critical LDAP deployments. If you need to support LDAP failover and federation, use Nexus Professional.

Comparing Nexus Open Source and Nexus Professional Features

The following table summarizes the differences between Nexus Open Source and Nexus Professional:

figs/web/nx-open-vs-pro-datasheet-4.png

History of Nexus

Proximity in December 2005 as he was trying to find a way to isolate his own systems from an incredibly slow ADSL connection provided by a Hungarian ISP. Proximity started as a simple web application to proxy artifacts for a small organization with connectivity issues. Creating a local on-demand cache for Maven artifacts from the Maven Central repository gave an organization access to the artifacts on the Maven Central Repository, but it also made sure that these artifacts weren’t downloaded over a very slow ADSL connection used by a number of developers. In 2007,

Sonatype asked Tamas to help create a similar product named Nexus. Nexus is currently considered the logical next step to Proximity. Nexus currently has an active development team, and portions of the indexing code from Nexus are also being used in m2eclipse.

Repository Management

Repository Management

Repository managers serve two purposes: they act as highly configurable proxies between your organization and the public Maven repositories and they also provide an organization with a deployment destination for its own generated artifacts. Just as Source Code Management (SCM) tools are designed to manage source artifacts, Repository Managers have been designed to manage and track external dependencies and artifacts generated by your build. They are an essential part of any enterprise or open-source software development effort, and they enable greater collaboration between developers and wider distribution of software.

Proxying Public Repositories

Proxying and caching a remote public repository can speed up your builds by reducing redundant downloads over the public Internet. If a developer in your organization needs to download version 2.5 of the Spring Framework and you are using Nexus, the dependencies (and the dependency’s dependencies) only need to be downloaded from the remote repository once.

With a high-speed connection to the Internet this might seem like a minor concern, but if you are constantly asking your developers to download hundreds of megabytes of third-party dependencies, the real cost savings are going to be the time it takes Maven to check for new versions of dependencies and to download dependencies over the public Internet.

Proxying and serving Maven dependencies from a local repository cache can save you hundreds of HTTP requests over the public Internet, and, in very large multi-module projects, this can shave minutes from a build.

Managing Releases and Snapshots

If your project is relying on a number of SNAPSHOT dependencies, Maven will need to regularly check for updated versions of these snapshots. Depending on the configuration of your remote repositories, Maven will check for SNAPSHOT updates periodically, or it might be checking for SNAPSHOT updates on every build. When Maven checks for a snapshot update it needs to interrogate the remote repository for the latest version of the SNAPSHOT dependency. Depending on your connection to the public Internet and the load on the Maven Central repository, a SNAPSHOT update can add seconds to your project’s build for each SNAPSHOT dependency you rely upon.

When you host a local repository proxy with Nexus, you reduce the amount of time it takes for Maven to check for a newer version as your build interacts with a local repository cache. If you develop software with SNAPSHOT dependencies, using a local repository manager will save you a considerable amount of time, your 5-10 second SNAPSHOT update checks against the public central repository are going to execute in hundreds of milliseconds (or less) when they are executed against a local resource.

Getting Control of Dependencies

In addition to the simple savings in time and bandwidth, a repository manager provides an organization with control over what is downloaded by Maven. You can include or exclude specific artifacts from the public repository, and having this level of control over what is downloaded from the Maven Central repository is a prerequisite for many organizations which have a need for strict standards for the quality and security of the dependencies used in an enterprise system.

If you want to standardize on a specific version of a dependency like Hibernate or Spring you can enforce this standardization by only providing access to a specific version of an artifact in Nexus. You might be concerned with making sure that every external dependency has a license compatible with your legal standards for adopting and integrating open source libraries. If you are producing an application which is distributed, you might want to make sure that no one inadvertently adds a dependency on a third-party library covered under a copy-left license like the GPL. All of this is possible with Nexus.

Repository managers are a central point of access to external binary software artifacts and dependencies your system relies upon. Nexus provides a level of control that is essential when you are trying to track and manage the libraries and frameworks your software depends upon.

A Nexus for Collaboration

Aside from the benefits of mediating access to remote repositories, a repository manager also provides an important platform for collaborative software development. Unless you expect every member of your organization to download and build every single internal project from source, you will want to provide a mechanism for developers and departments to share binary artifacts (both SNAPSHOTs and releases) for internal software projects. Internal groups often consume the APIs and systems which are generated by other internal groups, when you adopt Nexus as a deployment platform for internal artifacts, you can easily share components and libraries between groups of developers.

Nexus provides you with a deployment target for your software components. Once you install Nexus, you can start using Maven to deploy snapshots and releases to internal repositories which can then be combined with other repositories in repository groups. Over time, this central deployment point for internal projects becomes the fabric for collaboration between different development teams and operations. Nexus is the secret ingredient that allows an organization to scale its development effort without sacrificing agility.

What is a Repository?

Maven developers are familiar with the concept of a repository: a collection of binary software artifacts and metadata stored in a defined directory structure which is used by clients such as Apache Ivy to retrieve binaries during a build process. In the case of the Maven repository, the primary type of binary artifact is a JAR file containing Java bytecode, but there is no limit to what type of artifact can be stored in a Maven repository. For example, one could just as easily deploy documentation archives, source archives, Flash libraries and applications, or Ruby libraries to a Maven repository. A Maven repository provides a platform for the storage, retrieval, and management of binary software artifacts and metadata.

In Maven, every software artifact is described by an XML document called a Project Object Model (POM). This POM contains information that describes a project and lists a project’s dependencies - the binary software artifacts which a given component depends upon for successful compilation or execution.

When Maven downloads a dependency from a repository, it also downloads that dependency’s POM. Given a dependency’s POM, Maven can then download any other libraries which are required by that dependency. The ability to automatically calculate a project’s dependencies and transitive dependencies is made possible by the standard and structure set by the Maven repository.

Maven and other tools such as Ivy which interact with a repository to search for binary software artifacts, model the projects they manage, and retrieve software artifacts on-demand from a repository. When you download and install Maven without any customization, Maven will retrieve artifacts from a Maven Central repository which serves millions of Maven users every single day. While you can configure Maven to retrieve binary software artifacts from a collection of mirrors, the best-practice is to install Nexus and use it to proxy and cache the contents of Central on your own network. <indexterm>

In addition to Central, there are a number of major organizations such as Redhat, Sun Microsystems, and Codehaus which maintain separate repositories.

While this might seem like a simple, obvious mechanism for distributing artifacts, the Java platform existed for several years before the Maven project created a formal attempt at the first repository for Java artifacts. Until the advent of the Maven repository in 2002, a project’s dependencies were gathered in a manual, ad-hoc process and were often distributed with a project’s source code. As applications grew more and more complex, and as software teams developed a need for more complex dependency management capabilities for larger enterprise applications, Maven’s ability to automatically retrieve dependencies and model dependencies between components became an essential part of software development.

Release and Snapshot Repositories

A repository stores two types of artifacts: releases and snapshots. Release repositories are for stable, static release artifacts and snapshot repositories are frequently updated repositories that store binary software artifacts from projects under constant development.

While it is possible to create a repository which serves both release and snapshot artifacts, repositories are usually segmented into release or snapshot repositories serving different consumers and maintaining different standards and procedures for deploying artifacts. Much like the difference between a production network and a staging network, a release repository is considered a production network and a snapshot repository is more like a development or a testing network. While there is a higher level of procedure and ceremony associated with deploying to a release repository, snapshot artifacts can be deployed and changed frequently without regard for stability and repeatability concerns.

The two types of artifacts managed by a repository manager are:

Release

A release artifact is an artifact which was created by a specific, versioned release. For example, consider the 1.2.0 release of the commons-lang library stored in the Maven Central repository. This release artifact, commons-lang-1.2.0.jar, and the associated POM, commons-lang-1.2.0.pom, are static objects which will never change in the Maven Central repository. Released artifacts are considered to be solid, stable, and perpetual in order to guarantee that builds which depend upon them are repeatable over time. The released JAR artifact is associated with a PGP signature, an MD5 and SHA checksum which can be used to verify both the authenticity and integrity of the binary software artifact.

Snapshot

Snapshot artifacts are artifacts generated during the development of a software project. A Snapshot artifact has both a version number such as “1.3.0” or “1.3” and a timestamp in its name. For example, a snapshot artifact for commons-lang 1.3.0 might have the name commons-lang-1.3.0-20090314.182342-1.jar the associated POM, MD5 and SHA hashes would also have a similar name. To facilitate collaboration during the development of software components, Maven and other clients which know how to consume snapshot artifacts from a repository also know how to interrogate the metadata associated with a Snapshot artifact to retrieve the latest version of a Snapshot dependency from a repository.

A project under active development produces SNAPSHOT artifacts that change over time. A release is comprised of artifacts which will remain unchanged over time.

Repository Coordinates

Repositories and tools like Maven know about a set of coordinates including the following components: groupId, artifactId, version, and packaging. This set of coordinates is often referred to as a GAV coordinate which is short for “Group, Artifact, Version coordinate”. The GAV coordinate standard is the foundation for Maven’s ability to manage dependencies. Four elements of this coordinate system are described below:

groupId

A group identifier groups a set of artifacts into a logical group. Groups are often designed to reflect the organization under which a particular software component is being produced. For example, software components being produced by the Maven project at the Apache Software Foundation are available under the groupId org.apache.maven.

artifactId

An artifact is an identifier for a software component. An artifact can represent an application or a library; for example, if you were creating a simple web application your project might have the artifactId “simple-webapp”, and if you were creating a simple library, your artifact might be “simple-library”. The combination of groupId and artifactId must be unique for a project.

version

The version of a project follows the established convention of Major, Minor, and Point release versions. For example, if your simple-library artifact has a Major release version of 1, a minor release version of 2, and point release version of 3, your version would be 1.2.3. Versions can also have alphanumeric qualifiers which are often used to denote release status. An example of such a qualifier would be a version like “1.2.3-BETA” where BETA signals a stage of testing meaningful to consumers of a software component.

packaging

Maven was initially created to handle JAR files, but a Maven repository is completely agnostic about the type of artifact it is managing. Packaging can be anything that describes any binary software format including ZIP, SWC, SWF, NAR, WAR, EAR, SAR.

Addressing Resources in a Repository

Tools designed to interact Maven repositories translate artifact coordinates into a URL which corresponds to a location in a Maven repository. If a tool such as Maven is looking for version 1.2.0 of the commons-lang JAR in the group org.apache.commons, this request is translated into:

<repoURL>/org/apache/commons/commons-lang/1.2.0/commons-lang-1.2.0.jar

Maven would also download the corresponding POM for commons-lang 1.2.0 from:

<repoURL>/org/apache/commons/commons-lang/1.2.0/commons-lang-1.2.0.pom

This POM may contain references to other dependencies which would then be retrieved from the same repository using the same URL patterns.

The Maven Central Repository

The most useful Maven repository is the Maven Central Repository. The Maven Central repository contains almost 90,000 software artifacts occupying around 70 GB of disk space. You can look at Central as an example of how Maven repositories operate and how they are assembled. Here are some of the properties of release repositories such as the Maven Central repository:

Artifact Metadata

All software artifacts added to Central require proper metadata including a Project Object Model (POM) for each artifact which describes the artifact itself, and any dependencies that software artifact might have.

Release Stability

Once published to the Maven Central repository, an artifact and the metadata describing that artifact never change. This property of release repositories guarantees that projects which depend on releases will be repeatable and stable over time. While new software artifacts are being published to central every day, once an artifact is assigned a release number on Central, there is a strict policy against modifying the contents of a software artifact after a release.

Repository Mirrors

Central is a public resource, and it is currently used by the millions of developers who have adopted Maven and the tools that understand how to interact with the Maven repository structure. There are a series of mirrors for the Central repository which are constantly synchronized with Central. Users are encouraged to query central for project metadata and cryptographic hashes and they are encouraged to retrieve the actual software artifacts from one of Central’s many mirrors. Tools like Nexus are designed to retrieve metadata from Central and artifact binaries from mirrors.

Artifact Security

The Maven Central repository contains cryptographic hash cryptographic hashes and PGP signatures which can be used to verify the authenticity and integrity of software artifacts served from Central or one of the many mirrors of Central.

What is a Repository Manager

If you use Maven, you are using a repository to retrieve artifacts and Maven plugins. In fact, Maven used a Maven repository to retrieve core plugins that implement the bulk of the features used in your builds. Once you start to rely on repositories, you realize how easy it is to add a dependency on an open source software library available in the Maven Central repository, and you might start to wonder how you can provide a similar level of convenience for your own developers. When you install a repository manager, you are bringing the power of a repository like Central into your organization, you can use it to proxy Central, and host your own repositories for internal and external use. In this section, we discuss the core functionality which defines what a repository manager does.

Put simply, a repository manager provides two core features:

  • The ability to proxy a remote repository and cache artifacts saving both bandwidth and time required to retrieve a software artifact from a remote repository, and

  • The ability the host a repository providing an organization with a deployment target for software artifacts.

In addition to these two core features, a repository manager also allows you to manage binary software artifacts through the software development lifecycle, search and catalog software artifacts, audit development and release transactions, and integrate with external security systems such as LDAP. The following sections define the feature sets of Nexus Open Source and Nexus Professional.

Core Capabilities of a Repository Manager

The base-line features of a repository manager are a description of the core capabilities of Nexus Open Source. Nexus Open Source provides for the:

Management of Software Artifacts

A repository manager is able to manage packaged binary software artifacts. In Java development, this would include JARs containing bytecode, source, or javadoc. In other environments, such as Flex, this would include any SWCs or SWFs generated by a Flex build.

Management of Software Metadata

A repository manager should have some knowledge of the metadata which describes artifacts. In a Maven repository this would include project coordinates (groupId, artifactId, version, classifier) and information about a given artifact’s releases.

Proxying of External Repositories

Proxying an external repository yields more stable builds as the artifacts used in a build can be served to clients from the repository manager’s cache even if the external repository becomes unavailable. Proxying also saves bandwidth and time as checking for the presence of an artifact on a local network is often orders of magnitude faster than querying a heavily loaded public repository

Deployment to Hosted Repositories

Organizations which deploy internal snapshots and releases to hosted repositories have an easier time distributing software artifacts across different teams and departments. When a department or development group deploys artifacts to a hosted repository, other departments and development groups can develop systems in parallel, relying upon dependencies served from both release and snapshot repositories.

Searching an Index of Artifacts

When you collect software artifacts and metadata in a repository manager, you gain the ability to create indexes and allow users and systems to search for artifacts. With the Nexus index, an IDE such as Eclipse has almost instantaneous access to the contents of all proxy repositories (including the Central repository) as well as access to your own internal and 3rd party artifacts. While the Central repository transformed the way that software is distributed, the Nexus index format brings the power of search to massive libraries of software artifacts.

Infrastructure for Artifact Management

A repository manager should also provide the appropriate infrastructure for managing software artifacts and a solid API for extension. In Nexus, Sonatype has provided a plugin API which allows developers to customize both the behavior, appearance, and functionality of the tool.

Additional Features of a Repository Manager

Once you adopt the core features of a repository manager, you start to view a repository manager as a tool which enables more efficient collaboration between development groups. Nexus Professional builds upon the foundations of a repository manager and adds capabilities such as Procurement and Staging.

Managing Project Dependencies

Many organizations require some level of oversight over the open source libraries and external artifacts that are let into an organization’s development cycle. An organization could have specific legal or regulatory constraints which requires every dependency to be subjected to a rigorous legal or security audit before it is integrated into a development environment. Another organization might have an architecture group which needs to make sure that a large set of developers only has access to a well-defined list of dependencies or specific versions of dependencies. Using the Procurement features of Nexus Professional, managers and architecture groups have the ability to allow and deny specific artifacts from external repositories.

Managing a Software Release

Nexus Professional adds some essential workflow to the process of staging software to a release repository. Using Nexus Professional, developers can deploy to a staging directory which can trigger a message to a Release Manager or to someone responsible for QA. Quality assurance (or a development manager) can then test and certify a release having the option to promote a release to the release repository or to discard a release if it didn’t meet release standards. Nexus Professional’s staging features allow managers to specify which personnel are allowed to certify that a release can be promoted to a release repository giving an organization more control over what software artifacts are released and who can release them.

Integration with LDAP

Nexus integrates with an LDAP directory, allowing an organization to connect Nexus to an existing directory of users and groups. Nexus authenticates users against an LDAP server and provides several mechanisms for mapping existing LDAP groups to Nexus roles.

Advanced Security

Using Nexus Professional, an organization can define a master User Password Encryption Key. Each user will be given a separate Maven settings file with an encrypted password using the Maven Nexus plugin. When users interact with Nexus, Nexus uses the User Password Encryption Key to decrypt a user’s Nexus credentials avoiding the need to send an easily compromised plain-text password over the network.

Settings Templates

Nexus Professional allows you to define Maven settings templates for developers. Developers can then automatically receive updates to Maven settings (~/.m2/settings.xml) using the Maven Nexus plugin. The ability to define Maven settings templates and to distribute customized Maven settings files to developers makes it easy for an organization to change global profiles or repository configuration without relying on developers to manually install a new settings file in a development environment.

Support for Multiple Repository Formats

Nexus Professional supports the p2 and the OSGi Bundle repository format used by the new Eclipse provisioning platform and OSGi developers. You can use the p2 plugin to consolidate, provision, and control the plugins that are being used in an Eclipse IDE. Using Nexus procurement, repository groups, and proxy repositories to consolidate multiple plugin repositories, an organization can use Nexus Professional to standardize the configuration of Eclipse IDE development environments.

Reasons to Use a Repository Manager

Here are a few reasons why using a repository manager is an imperative. While most people wouldn’t even think of developing software without the use of a source code control system like Subversion or Perforce, the concept of using a repository manager is still something that needs development. There are many who use Maven for years without realizing the benefits of using a repository manager. This section was written as an attempt to capture some of the benefits of using a repository manager.

Speed Up Your Builds

When you run your multi-module project in Maven, how do you think Maven knows if it needs to update plugins or snapshot dependencies? It has to make a request for each artifact it needs to test. Even if nothing has changed, if your project depends on a few SNAPSHOTs or if you don’t specify plugin version, Maven might have to make tens to hundreds of requests to a remote repository. All of these requests over the public Internet add up to real, wasted, time. I’ve seen complex builds cut build time by 75% after installing a local instance of Nexus. You are wasting time better spent coding waiting for your build to needlessly interrogate a remote Maven repository.

Save Bandwidth

The larger the organization, the more critical bandwidth savings can be. If you have thousands of developers regularly wasting good bandwidth to download the same files over and over again, using a repository manager to keep a local cache is going to save you a good deal of bandwidth. Even for smaller organizations with limited budgets for connectivity and IT operations, having to deal with a set of developers maxing out your connection to the Internet to download the same things over and over again seems backwards.

Ease the Burden on Central

Running the Maven Central repository is no short order. It ain’t cheap to serve the millions of requests and Terabytes of data required to satisfy the global demand for software artifacts from the Maven Central repository. Something as simple as installing a repository manager at every organization that uses Maven would likely cut the bandwidth requirements for Central by at least half. If you have more than a couple developers using Maven, install a repository manager for the sake of keeping Central available and in business.

Gain Predictability and Scalability

How often in the past few years has your business come to a crashing halt because of an outage? Depending on Central for your day to day operations also means that you depend on having Internet connectivity (and on the fact the Central will remain available 24/7). While Sonatype is confident in its ability to keep Central running 24/7, you should take some steps of your own to make sure that your development team isn’t going to be surprised by some network outage on either end. If you have a local repository manager, like Nexus, you can be sure that your builds will continue to work even if you lose connectivity.

Control and Audit Dependencies and Releases

So, you’ve moved over to Maven (or maybe Ivy, Ivy reads the same repository), and you now have a whole room full of developers who feel empowered to add or remove dependencies and experiment with new frameworks. We’ve all seen this. We’ve all worked in places with a developer who might be more interested in experimenting than in working. It is unfortunate to say so, but there are often times when an architect, or an architecture group needs to establish some baseline standards which are going to be used in an organization. Nexus provides this level of control. If you need more oversight over the artifacts that are making it into your organization, take a look at Nexus. Without a repository manager, you are going to have little control over what dependencies are going to be used by your development team.

Deploy 3rd Party Artifacts

How do you deal with that one-off JAR from a vendor that is not open source, and not available on the Maven Central repository? You need to deploy these artifacts to a repository and configure your Maven instance to read from that repository. Instead of handcrafting some POMs, download Nexus and take the two or three minutes it is going to take to get your hands on a tool that can create such a repository from 3rd-party artifacts. Nexus provides an intuitive upload form that you can use to upload any random free-floating JAR that finds its way into your project’s dependencies.

Collaborate with Internal Repositories

Many organizations require every developer to checkout and build the entire system from source simply because they have no good way of sharing internal JARs from a build. You can solve a problem like this by splitting projects up and using Nexus as an internal repository to host internal dependencies.

For example, consider a company that has 30 developers split into three groups of 10, each group focused on a different part of the system. Without an easy way to share internal dependencies, a group like this is forced either to create an ad hoc filesystem-based repository or to build the system in its entirety so that dependencies are installed in every developer’s local repository.

The alternative is to separate the projects into different modules that all have dependencies on artifacts hosted by an internal Nexus repository. Once you’ve done this, groups can collaborate by exchanging compiled snapshot and release artifacts via Nexus. In other words, you don’t need to ask every developer to checkout a massive multi-module project that includes the entire organization’s code. Each group within the organization can deploy snapshots and artifacts to a local Nexus instance, and each group can maintain a project structure which includes only the projects it is responsible for.

Distribute with Public Repositories

If you are an open source project, or if you release software to the public, Nexus can be the tool you use to serve artifacts to external users. Think about it this way… When was the last time you cut a release for your software project? Assuming it wasn’t deployed to a Maven repository, you likely had to write some scripts to package the contents of the release, maybe someone special had to sign the release with a super-secret cryptographic key. Then, you had to upload it to some web server, and then make sure that the pages that describe the upload were themselves updated. Lots of needless complexity…

If you were using something like Nexus, which can be configured to expose a hosted repository to the outside world, you could use the packaging and assembly capabilities of Maven and the structure of the Maven repository to make a release that is more easily consumed. And, this isn’t just for JAR files and Java web applications; Maven repositories can host any kind of artifact. Nexus, and Maven repositories in general, define a known structure for releases. If you are writing some Java library, publishing it to your own Nexus instance serving a public repository will make it easier for people to start using your code right away.

Adopting a Repository Manager

This section talks about the stages of moving to a repository manager. Adopting a repository manager is not an all or nothing proposition, and there are various levels (or stages) of adoption that can be distinguished when approaching repository management. On one end of the adoption spectrum is the organization that installs a repository manager just to control and consolidate access to a set of remote repositories. On the other end of the spectrum is the organization which has integrated the repository manager into an efficient software development lifecycle, using it to facilitate decision points in the lifecycle, encouraging more efficient collaboration throughout the enterprise, and keeping detailed records to increase visibility into the software development process.

Stage Zero: Before Using a Repository Manager

While this isn’t a stage of adoption, Stage Zero is a description of the way software builds work in the absence of a repository manager. When a developer decides that a he needs a particular open source software component, he will download it from the component’s website, read the documentation, and find the additional software that his components rely on (referred to as “dependencies”). Once he has manually assembled a collection of dependencies from various open source project web sites and proprietary vendors, he will place all these components somewhere on the network so that he, his team members, the build script, the QA team, and the production support team can find it. At any time, other developers may bring in other components, sometimes with overlapping dependencies, placing them in different network locations. The instructions to bring all of these ad-hoc, developer-managed components libraries together in a software build process can become very complicated and hard to maintain.

Maven was introduced to improve this build process by introducing the concept of structured repositories from which the build scripts can retrieve the software components. In Maven language, these software components or dependencies are referred to as “artifacts”, a term which can refer to any generic software artifact including components, libraries, frameworks, containers, etc. Maven can identify artifacts in repositories, understand their dependencies, retrieve all that are needed for a successful build, and deploy its output back to repositories when done.

Developers using Maven without a repository manager find most of their software artifacts and dependencies in Maven Central. If they happen to use another remote repository or if they need to add a custom artifact, the solution, in Stage Zero, is to manually manipulate the files in a local repository and share this local repository with multiple developers. While this approach may yield a working build for a small team, managing a shared local repository doesn’t allow an organization to scale a development effort. There is no inherent control over who can set up a local repository, who can add to them or change or delete from them, nor are there tools to protect the integrity of these repositories.

That is, until Repository Managers were introduced.

Stage One: Proxying Remote Repositories

This is the easiest stage to understand both in terms of benefits to an organization and action required to complete this stage. All you need to do to start proxying a remote repository is to deploy Nexus and start the server with the default configuration. Configure your Maven clients to read from the Nexus public repository group, and Nexus will automatically retrieve artifacts from remote repositories, such as Maven Central, caching them locally.

Without a repository manager, your organization might have hundreds of developers independently downloading the same artifacts from public, remote repositories. With a repository manager, these artifacts can be downloaded once and stored locally. After Stage One, your builds run considerably faster than they did when you relied upon the Maven Central repository.

Once you’ve installed Nexus and you’ve configured all of your organization’s clients to use it as a single point of access to remote repositories, you begin to realize that it now provides you with a central configuration point for the artifacts used throughout your organization. Once you’ve started to proxy, you can start to think about using Nexus as a tool to control policy and what dependencies are allowed to be used in your organization. Nexus Professional provides a procurement plugin which allows for fine-grained control over which artifacts can be accessed from a remote repository. This procurement feature is described in more detail in the section which deals with Lifecycle Integration.

Stage Two: Hosting a Repository Manager

Once you have started to proxy remote repositories and you are using Nexus as a single, consolidated access point for remote repositories, you can start to deploy your own artifacts to Nexus hosted repositories. Most people approach repository management to find a solution for proxying remote repositories, and while proxying is the most obvious and immediate benefit of installing a repository manager, hosting internally generated artifacts tends to be the stage that has the most impact on collaboration within an organization.

To understand the benefits of hosting an internal repository, you have to understand the concept of managing binary software artifacts. Software development teams are very familiar with the idea of a source code repository or a source code management tool. Versioning control systems such as Subversion, Clearcase, Git, and CVS provide solid tools for managing the various source artifacts that comprise a complex enterprise application, and developers are comfortable checking source out from source control to build enterprise applications. However, past a certain point in the software development lifecycle, source artifacts are no longer relevant. A QA department trying to test an application or an Operations team attempting to deploy an application to a production network no longer needs access to the source artifacts. QA and Operations are more interested in the compiled end-product of the software development lifecycle: the binary software artifacts. A repository manager allows you to version, store, search, archive, and release binary software artifacts derived from the source artifacts stored in a source control system. A repository manager allows you to apply the same systematic operations on binary software artifacts which you currently apply to your source code.

When your build system starts to deploy artifacts to an internal repository, it changes the way that developers and development groups can interact with one another in an enterprise. Developers in one development group can code and release a stable version of an internal library, deploy this library to an internal Nexus release repository, and so share this binary artifact with another group or department. Without a repository manager managing internal artifacts, you have ad-hoc solutions and the organizational equivalent of "duct tape". How does the infrastructure group send a new library to the applications group without Nexus? Someone copies a file to a shared directory, and sends an email to the team lead. Organizations without repository managers are full of these ad-hoc processes that get in the way of efficient development and deployment.

With a repository manager, every developer and every development group within the enterprise understands and interacts with a common collaborative structure: the repository manager. Do you need to interact with the Commerce team’s new API? Just add a dependency to your project and Maven will retrieve the library from Nexus automatically.

One of the other direct benefits of deploying your own artifacts to a repository such as Nexus is the ability to quickly search the metadata and contents of those artifacts both via a web UI and through IDE integration tools such as m2eclipse. When you start to deploy internal artifacts you can synchronize all development groups to a common versioning and naming standard, and you can use the highly configurable authentication and role-based access controls to control which developers and which development groups can deploy artifacts to specific repositories or paths within a repository.

Stage Three: Continuous Collaboration

Developing this collaborative model further, if your application is being continuously built and deployed using a tool like Hudson, a developer can checkout a specific module from a large multi-module build and not have to constantly deal with the entire source tree at any given time. This allows a software development effort to scale efficiently. If every developer working on a complex enterprise application needs to checkout the entire source tree every time he or she needs to make a simple change to a small component, you are quickly going to find that building the entire application becomes a burdensome bottleneck to progress. The larger your enterprise grows, the more complex your application becomes, the larger the collective burden of wasted time and missed opportunities. A slow enterprise build prevents the quick turnaround or quick feedback loop that helps your developers maintain focus during a development cycle.

Once you are building with Maven, sharing binary artifacts with Nexus, continuously testing and deploying with Hudson, and generating reports and metrics with tools like Sonar, your entire organization gains a collaborative "central nervous system" that enables a more agile approach to software development.

Stage Four: Lifecycle Integration

Once you’ve configured a repository manager to proxy remote repositories and you are using a repository manager as an integration point between developers and departments, you start to think about the various ways your repository manager can be used to support the decisions that go into software development. You can start using the repository manager to stage releases and supporting the workflow associated with a managed release, and you can use the procurement features of a tool like Nexus Professional to give management more visibility into the origins, characteristics and open source licenses of the artifacts used during the creation of an enterprise application.

Nexus Professional enables organizations to integrate the management of software artifacts tightly with the software development lifecycle: Developer Onboarding, Provisioning, Compliance, Procurement, Enterprise Security, Staging and other capabilities that support the workflow that surrounds a modern software development effort.

Developer Onboarding

Using Nexus Professional’s support for Eclipse plugin repositories, Nexus can be used to dramatically reduce the time required to provision a new Eclipse environment for a new developer. Using Nexus’ p2 repository support, a developer’s IDE can be quickly configured from a set of Eclipse plugins managed and procured via Nexus Professional and delivered directly to the developer’s desktop.

Using Nexus Professional’s Maven Settings management feature and integrated security features you can configure a developer’s Maven settings by running a single, convenient Maven goal and downloading customized settings for a particular developer. When you use Maven and Nexus Professional together, developers can get up and running quickly, collaborating on projects that share common conventions without having to manually install dependencies in local repositories.

Provisioning

Using Nexus as an integration point between Engineering and Operations means that Engineering can be responsible for delivering solid, tested artifacts to Quality Assurance and Operations via a standard repository format. Often development teams are roped into the production deployment story and become responsible for building entire production environments within a build system. This conflates software engineering with system administration and blurs the line between Engineering and Operations. If you use Nexus as a end-point for releases from Engineering, Operations can then retrieve, assemble, and configure an application from tested components in the Nexus repository.

Compliance

Procurement, staging, and audit logs are all features which increase the visibility into who and what is involved with your software development effort. Using Nexus Professional, Engineering can create the reports and documents which can be used to facilitate discussions about oversight. Organizations subject to various regulations often need to produce a list of components involved in a software release. Legal departments often require a list of open source licenses being used in a particular software component, and managers often lack critical visibility into the software development process.

Procurement

The ease with which today’s developer can add a dependency on a new open source library and download this library from a Central repository has a downside. Organizations large and small are constantly wondering what open source libraries are being used in applications, and whether these libraries have acceptable open source licenses for distribution. The Procurement features of Nexus Professional give architects and management more oversight over the artifacts which are allowed into an organization. Using the Procurement features, a Nexus administrator or Procurement manager can allow or deny specific artifacts by group, version, or path. You can use the procurement manager as a firewall between your own organization’s development environment and the 95,000 artifacts available on the Maven Central repository.

Enterprise Security

Nexus’ LDAP integration allows an enterprise to map existing LDAP groups to Nexus roles and provides Nexus administrators with a highly configurable interface to control which individuals or groups have access to a fine-grained set of Nexus permissions.

Staging

Nexus Professional adds an important step to the software release workflow, adding the concept of a managed (or staged) release to a hosted repository. When a developer needs to perform a production release, Nexus Professional can isolate the artifacts involved in a release in a staged repository which can then be certified and tested. A manager or a quality assurance tester can then promote or discard a release. The staging feature allows you to specify the individuals that are allowed to promote a release and keeps an audit of who was responsible for testing, promoting, or discarding a software release.

Installing and Running Nexus

Downloading Nexus

There are two distributions of Nexus: Nexus Open Source and Nexus Professional. Nexus Open Source is a fully-featured repository manager which can be freely used, customized, and distributed under the GNU Affero General Public License (AGPL) Version 3. Nexus Professional is a distribution of Nexus with features that are relevant to large enterprises and organizations which require complex procurement and staging workflows in addition to more advanced LDAP integration, Atlassian Crowd support, and other development infrastructure. The differences between Nexus Open Source and Nexus Professional are explored in the previous chapter.

Downloading Nexus Open Source

Download Nexus Open Source from http://nexus.sonatype.org/download-nexus.html then download the appropriate Nexus Open Source distribution by clicking on the appropriate archive as shown in <xref linkend="fig-installing_open-source-dl-select" />. Nexus Open Source is available as a ZIP and a Gzip’d TAR file under the file names ${nexusopen.bundle.name}.zip and ${nexusopen.bundle.name}.tgz

figs/web/installing_open-source-dl.png
Figure 1. Downloading Nexus Open Source from nexus.sonatype.org
figs/web/installing_open-source-dl-select.png
Figure 2. Selecting the Nexus Open Source Distribution Download

Nexus Open Source can also be deployed as a web application in a servlet container like Jetty or Tomcat or an application server like Glassfish or JBoss. Instructions for installing Nexus as a WAR are found in <xref linkend="install-sect-as-a-war" />.

Downloading Nexus Professional

To download Nexus Professional, go to the Nexus Trial evaluation form.

Fill out the form and then check your email account for download instructions. After filling out a brief contact form and agreeing to the evaluation license, you will be sent an email with a link to download the Nexus Professional distribution. Nexus is available as a ZIP file under the file names ${nexus.bundle.name}.zip and ${nexus.bundle.name}.tgz

Installing Nexus

The following sections detail the installation process for both Nexus Open Source and Nexus Professional.

Nexus Prerequisites

Nexus Open Source and Nexus Professional only have one prerequisite, a Java Runtime Environment (JRE) compatible with Java 5 or higher. Nexus is most often run with the JRE that is bundled with a Java Development Kit (JDK) installation, and it can be run with the latest version of Sun’s JDK for Java 5 or Java 6. To download the latest release of the Sun JDK, go to http://developers.sun.com/downloads/, and download the latest Java 6 JDK or an older Java 5 JDK, either will work but Java 6 is recommended.

Installing Nexus Open Source

The following instructions are for installing Nexus Open Source as a stand-alone server. Nexus comes bundled with a Jetty instance which listens to all configured IP addresses on a host (0.0.0.0) and runs on port 8081 by default. If you would like to run Nexus Open Source as a web application in an existing application server or servlet container, please refer to the instructions in <xref linkend="install-sect-as-a-war" />.

Installing Nexus Open Source is straightforward. Unpack the Nexus web application archive in a directory. If you are installing Nexus on a local workstation to give it a test run, you can install it in your home directory or wherever you like; Nexus doesn’t have any hard coded directories, it will run from any directory. If you downloaded the ZIP

$ unzip ${nexusopen.bundle.name}.zip

And, if you download the GZip’d TAR archive, run:

$ tar xvzf ${nexusopen.bundle.name}.tgz
Note There are some known incompatibilities with the version of tar provided by Solaris and the gzip tar format. If you are installing Nexus on Solaris, you must use the GNU tar application, or you will end up with corrupted files.
Note If you are installing Nexus on a server, you might want to use a directory other than your home directory. On a Unix machine, this book assumes that Nexus is installed in /usr/local/${nexusopen.version.name} with a symbolic link /usr/local/nexus to the nexus directory. Using a generic symbolic link nexus to a specific version is a common practice which makes it easier to upgrade when a newer version of Nexus is made available.
$ sudo cp ${nexusopen.bundle.name}.tgz /usr/local
$ cd /usr/local
$ sudo tar xvzf ${nexusopen.bundle.name}.tgz
$ ln -s ${nexusopen.version.name} nexus

Although it isn’t required for Nexus to run, you may want to set an environment variable NEXUS_HOME in your environment which points to the installation directory of Nexus. This chapter will refer

The Nexus installation directory ${nexusopen.version.name} has a sibling directory named sonatype-work. This directory contains all of the repository and configuration data for Nexus and is stored outside of the Nexus installation directory to make it easier to upgrade to a newer version of Nexus. By default, this directory is always a sibling to the nexus installation directory; if you installed nexus in /usr/local directory would also contain a sonatype-work subdirectory containing all of the content and configuration. The location of the sonatype-work directory can be customized by altering the nexus-work

Installing Nexus Professional

The following instructions are for installing Nexus Professional as a stand-alone server. Nexus Professional is bundled with a Jetty instance which listens to all configured IP addresses on a host (0.0.0.0) and runs on port 8081 by default.

Installing Nexus is straightforward, unpack the Nexus web application archive in a directory. If you are installing Nexus on a local workstation to give it a test run, you can install it in your home directory or wherever you like; Nexus doesn’t have any hard coded directories, it will run from any directory. If you downloaded the ZIP

$ unzip ${nexus.bundle.name}.zip

And, if you download the GZip’d TAR archive, run:

$ tar xvzf ${nexus.bundle.name}.tgz

If you are installing Nexus on a server, you might want to use a directory other than your home directory. On a Unix machine, this book assumes that Nexus is installed in /usr/local/${nexus.version.name} with a symbolic link /usr/local/nexus to the nexus directory. Using a symbolic link nexus to a directory which holds a specific version of Nexus is a common practice that makes it easier to upgrade to a newer version of Nexus.

$ sudo cp ${nexus.bundle.name}.tgz /usr/local
$ cd /usr/local
$ sudo tar xvzf ${nexus.bundle.name}.tgz
$ ln -s ${nexus.version.name} nexus

Although it isn’t required for Nexus to run, you may want to set an environment variable NEXUS_HOME in your environment which points to the installation directory of Nexus. This chapter will refer to this ${nexus.version.name} has a sibling directory named sonatype-work. This directory contains all of the repository and configuration data for Nexus and is stored outside of the Nexus installation directory to make it easier to upgrade to a newer version of Nexus.

Upgrading Nexus

Since Nexus separates its configuration and data storage from the application, it is easy to upgrade an existing Nexus installation. To upgrade Nexus, unpack the Nexus archive in the directory which contains the existing Nexus installation. Once the archive is unpacked, the new Nexus application directory should be a sibling to your existing sonatype-work/ directory. If you have defined a symbolic link for the version of Nexus to use, change that to point at the new Nexus application directory. When you start the new instance of Nexus it will read the existing repository configuration from the sonatype-work/

Running Nexus

When you start Nexus, you are starting a web server on the default port of 0.0.0.0:8081. Nexus runs within a servlet container called Jetty and it is started with a native service wrapper called the Tanuki Java Service Wrapper. This service wrapper can be configured to run Nexus as a Windows service or a Unix daemon. To start Nexus, you will need to find the appropriate startup script for your platform. To see the list of available platforms, list the contents of the

The following example listing starts Nexus using the script for Mac you the available platforms, then we make the contents of the bin directory executable with chmod. The Mac OS X wrapper is started with a call to nexus start, and then we tail the wrapper.log in stating what IP address and port it is listening on.

$ cd /usr/local/nexus
$ ls ./bin/jsw/
conf/                linux-x86-64/        solaris-x86-32/
lib/                 macosx-universal-32/ windows-x86-32/
license/             macosx-universal-64/ windows-x86-64/
linux-ppc-64/        solaris-sparc-32/
linux-x86-32/        solaris-sparc-64/
$ chmod -R a+x bin
$ ./bin/jsw/macosx-universal-64/nexus start
Starting Nexus Repository Manager...
Started Nexus Repository Manager.
$ tail -f logs/wrapper.log
INFO  ... [ServletContainer:default] - SelectChannelConnector@0.0.0.0:8081

At this point, Nexus will be running and listening on all IP addresses (0.0.0.0) that are configured for the current host on port 8081. To use Nexus, fire up a web browser and type in the URL: http://localhost:8081/nexus

While we use "localhost" throughout this book, you may need to use the IP Loopback Address of "127.0.0.1" or the IP address assigned to the machine running Nexus. Click on the "Log In" link in the upper right-hand corner of the web page, and you should see the login dialog. THE DEFAULT NEXUS USERNAME AND PASSWORD IS "admin" AND "admin123".

figs/web/installation_default-admin.png
Figure 3. Default Nexus Administrative Credentials (admin/admin123)
figs/web/repository-manager_nexus-login.png
Figure 4. Nexus Application Window (default login/password is admin/admin123)

Post-Install Checklist

Nexus ships with some default passwords and settings for repository indexing that need to be changed for your installation to be useful (and secure). After installing and running Nexus, you need to make sure that you complete the following tasks:

Step 1: Change the Administrative Password and Email Address

The administrative password defaults to admin123. The first thing you should do to your new Nexus installation is change this password. To change the administrative password login as "admin" with the password "admin123", and click on Change Password under the Security menu in the left-hand side of the browser window. For more detailed instructions, see <xref linkend="using-sect-changing-password" />.

Step 2: Configure the SMTP Settings

Nexus can send username and password recovery emails, to enable this feature, you will need to configure Nexus with a SMTP Host and Port as well as any necessary authentication parameters that Nexus needs to connect to the mail server. To configure the SMTP settings, load the server configuration dialog shown in <xref linkend="fig-nexus-server-config" />.

Step 3: Enable Remote Index Downloads

Nexus ships with three important proxy repositories for the Maven Central repository, Apache Snapshot repository, and the Codehaus Snapshot repository. Each of these repositories contains thousands (or tens of thousands) of artifacts and it would be impractical to download the entire contents of each. To that end, most repositories maintain an index which catalogs the entire contents and provides for fast and efficient searching. Nexus uses these remote indexes to search for artifacts, but we’ve disabled the index download as a default setting. To download remote indexes:

  1. Click on Repositories under the Administration menu in the left-hand side of the browser window.

  2. Select each of the three proxy repositories and change Download Remote Indexes to true in the Configuration tab. You’ll need to load the dialog shown in <xref linkend="fig-repo-config" /> for each of the three repositories.

This will trigger Nexus to re-index these repositories, during which the remote index files will be downloaded. It might take Nexus a few minutes to download the entire index, but once you have it, you’ll be able to search the entire contents of the Maven repository.

Once you’ve enabled remote index downloads, you still won’t be able to browse the complete contents of a remote repository. Downloading the remote index allows you to search for artifacts in a repository, but until you download those artifacts from the remote repository they will not show in the repository tree when you are browsing a repository. When browsing a repository, you will only be shown artifacts which have been downloaded from the remote repository.

Step 4: Change the Deployment Password

The deployment user’s password defaults to deployment123. Change this password to make sure that only authorized developers can deploy artifacts to your Nexus installation. To change the deployment password: log in as an administrator, click on Security to expand the Security menu, then click on Users. You should then see a list of users. Right-click on the deployment user and select "Set Password".

Step 5: Install Professional License (Nexus Professional Only)

If you are running Nexus Professional and you have purchased a license from Sonatype, you will need to upload your license. This license will be emailed to you after you have purchased Nexus Professional from http://store.sonatype.com. To load the License tab, click on Licensing under the Enterprise menu in the Nexus application menu. For more information about installing a Nexus Professional license file, see <xref linkend="installing-sect-licensing" />.

Step 6: If necessary, set the LANG Environment Variable

If your Nexus instance needs to store configuration and data using an international character set, you should set the LANG environment variable. The Java Runtime will adapt to the value of the LANG environment variable and ensure that configuration data is saved using the appropriate character type. If you are starting Nexus as a service, place this environment variable in the startup script found in /etc/init.d/nexus. For more information about locale settings in Ubuntu read https://help.ubuntu.com/community/Locale

Configuring Nexus as a Service

When installing Nexus, you will often want to configure Nexus as a service. If you are on Windows, the Nexus distribution includes binaries that can work with the Windows Services subsystem and if you are on another platform such as GNU/Linux Nexus also includes scripts that can be configured to start Nexus as a service. The following sections provide instructions for configuring Nexus as a service.

Startup Scripts for GNU/Linux

You can configure Nexus to start automatically, by copying the nexus script to the /etc/init.d directory. On a GNU/Linux system (tested with Redhat, Fedora, Ubuntu, or CentOS) perform the following operations as the root user:

  1. Make the /etc/init.d/nexus script executable - chmod 755 /etc/init.d/nexus

  2. Edit this script changing the following variables:

    1. Change APP_NAME

    2. Change APP_LONG_NAME to "Sonatype Nexus"

    3. Add a variable NEXUS_HOME which points to your Nexus installation directory

    4. Add a variable PLATFORM which contains either linux-x86-32, linux-x86-64, or linux-ppc-64

  3. Change PIDDIR to /var/run

  4. Add a JAVA_HOME variable which points to your local Java installation

  5. (Optional) Set the RUN_AS_USER to "nexus". If you do this, you will need to:

    1. Create a nexus user

    2. Change the Owner and Group of your nexus install directory to nexus

Note If you set the "RUN_AS_USER" variable, you’ll have to change the "pid" directory to point to a directory where this user has read/write permissions. In most Linux distributions, /var/run is only writable by root. The properties that would need to be added to customize the PID file location is "wrapper.pid". For more information about this property and how it would be configured in wrapper.conf, see: http://wrapper.tanukisoftware.com/doc/english/properties.html
figs/web/installing_bin-dir-l32.png
Figure 5. Script Directory for 32-bit GNU/Linux

At the end of this you should have a file in /etc/init.d/nexus which starts with a series of configuration properties which look something like this (assuming that you’ve installed Nexus in /usr/local/nexus and that you have Java installed in /usr/java/latest

JAVA_HOME=/usr/java/latest
PATH=\${PATH}:\${JAVA_HOME}/bin
APP_NAME="nexus"
APP_LONG_NAME="Sonatype Nexus"
NEXUS_HOME=/usr/local/nexus
PLATFORM=linux-x86-64
WRAPPER_CMD="\${NEXUS_HOME}/bin/jsw/\${PLATFORM}/wrapper"
WRAPPER_CONF="\${NEXUS_HOME}/bin/jsw/conf/wrapper.conf"
PRIORITY=
PIDDIR="/var/run"
#RUN_AS_USER=nexus
Add Nexus as a Service on Redhat, Fedora, and CentOS

This script has the appropriate chkconfig directives, so all you need to do to add Nexus as a service is run the following commands:

$ cd /etc/init.d
$ chkconfig --add nexus
$ chkconfig --levels 345 nexus on
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

The second command adds nexus as a service to be started and stopped with the service command and managed by the chkconfig manages the symbolic links in /etc/rc[0-6].d which control the services to be started and stopped when the operating system restarts or transitions between run-levels. The third command adds nexus to run-levels 3, 4, and 5. The service command starts Nexus, and the last command tails the wrapper.log to verify that Nexus has been started successfully. If Nexus has started successfully, you should see a message notifying you that Nexus is listening for HTTP

Add Nexus as a Service on Ubuntu

The process for setting Nexus up as a service on Ubuntu differs slightly from the process used on a Redhat variant. Instead of running chkconfig, you should run the following sequence of commands once you’ve configured the startup script in /etc/init.d

$ cd /etc/init.d
$ update-rc.d nexus defaults
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

Running Nexus Behind a Proxy

If you installed Nexus as a stand-alone application, Nexus is running on a high-performance servlet container based on Java NIO. From a performance perspective, there is no reason for you not to run Nexus by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate multiple disparate applications using tools like mod_rewrite. For this reason, we’ve included some brief instructions for configuration Apache httpd. We assume that you’ve already installed Apache 2, and that you are using a Virtual Host for www.somecompany.com.

Let’s assume that you wanted to host Nexus behind Apache HTTPd at the URL http://www.somecompany.com. To do this, you’ll need to change the context path that Nexus is served from.

  1. named webapp-context-path. Change this value from "/nexus" to "/"

  2. Restart Nexus and Verify that it is available on http://localhost:8081/

  3. Clear the Base URL in Nexus as shown in <xref linkend="fig-nexus-server-config-3" /> under Application Server Settings.

At this point, edit the HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Nexus via mod_proxy at http://www.somecompany.com/

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost *:80>
  ServerName www.somecompany.com
  ServerAdmin admin@somecompany.com
  ProxyPass / http://localhost:8081/
  ProxyPassReverse / http://localhost:8081/
  ErrorLog logs/somecompany/nexus/error.log
  CustomLog logs/somecompany/nexus/access.log common
</VirtualHost>

If you just wanted to continue to serve Nexus at the /nexus context path, you would not change the contextPath in in your ProxyPass and ProxyPassReverse

  ProxyPass /nexus/ http://localhost:8081/nexus/
  ProxyPassReverse /nexus/ http://localhost:8081/nexus/

Apache configuration is going to vary based on your own application’s requirements and the way you intend to expose Nexus to the outside world. If you need more details about Apache httpd and mod_proxy, please see http://httpd.apache.org

Installing the Nexus WAR

The Nexus Open Source WAR has been successfully tested in Tomcat, Jetty, and Resin. If you need to run Nexus under Glassfish, please see <xref linkend="install-sect-war-gf" />. To download the Nexus Open Source WAR, go to http://nexus.sonatype.org/using/download.html. Click on the Download Site link and then download the Nexus WAR. Once you have downloaded the Nexus Open Source WAR, you can install it in a servlet container or application server.

The process for installing a WAR in an servlet container or application server is going to vary for each specific application. Often, this installation process is as simple as dropping a WAR file in a special directory and restarting the container. For example, to install the Nexus WAR in Tomcat, drop the your Tomcat instance. Assuming that Tomcat is configured on port 8080 once Tomcat is started, Nexus will be available on http://localhost:8080/nexus-webapp-1.6.0.

If you would like a less verbose URL, copy nexus-webapp-1.6.0.war to a file named nexus.war before copying the distribution to

Note When installing Nexus as a WAR in an application server or servlet container, it automatically creates a sonatype-work directory in ~/sonatype-work. This directory contains all of the necessary configuration and repository storage for Nexus.

Running the Nexus WAR in Glassfish

There is a known logging configuration conflict between the Nexus Open Source WAR and Glassfish. To address this conflict, you will need to modify the log4j.properties file and change a few of the directives that print messages to the console. The log4j.properties file is located in /sonatype-work/conf/log4j.properties. This file is created the first time you attempt to deploy Nexus to Glassfish. To create this file, deploy Nexus to Glassfish. While this initial deployment will fail due to a logging conflict, the act of deploying Nexus to Glassfish will create the working directory in /sonatype-work and the log4j.properties

Edit this log4j.properties file as follows:

  1. On the first line, change "log4j.rootLogger=INFO, console," to "logfilelog4j.rootLogger=INFO, logfile"

  2. Remove the last three lines starting with "log4j.appender.console"

These changes will instruct Log4J not to print messages to the console. Once you make these edits, restart Glassfish.

Installing a Nexus Professional License

To install a Nexus Professional license, click on Licensing in the Enterprise menu. Clicking on Licensing will bring up the panel shown in <xref linkend="fig-installations-licensing" />. To upload your Nexus Professional license, click on Browse…, select the file, and click on Upload.

figs/web/repository-manager_license.png
Figure 6. Nexus Professional Licensing Panel

Once you have selected a license and uploaded it to Nexus, Nexus Professional will display a dialog box with the Nexus Professional End-user License Agreement as shown in <xref linkend="fig-installation-eula" />. If you agree with the terms and conditions, click on "I Agree".

figs/web/installing_license_eula.png
Figure 7. Nexus Professional End-user License Agreement

Once you have agreed to the terms and conditions contained in the End User License Agreement, Nexus Professional will then display a dialog box confirming the installation of a Nexus Professional license as shown in <xref linkend="fig-installation-license-upload-config" />.

figs/web/installing_license_uploaded.png
Figure 8. License Upload Finished Dialog

If you need to move your Nexus Professional license, you can click on the "Uninstall License" button at the bottom of the Licensing Panel. Clicking on this button will show the dialog in <xref linkend="fig-installation-config-uninstall" /> which confirms that you want to uninstall a license.

figs/web/installing_uninstall_license.png
Figure 9. Uninstall License Confirmation Dialog

Clicking Yes in this dialog box will uninstall the license from Nexus Professional and display another dialog which confirms that the license has been successfully uninstalled.

figs/web/installing_uninstall_completed.png
Figure 10. License Uninstall Completed Dialog

Evaluation Expiration

If you have downloaded the Nexus Professional evaluation, you will have thirty days to evaluate the product. After the expiration of this thirty day evaluation period, Nexus Professional will revert back to Nexus Open Source. To reactivate Nexus Professional after the end of your evaluation period, contact a Sonatype sales representative at sales@sonatype.com

Sonatype Nexus Directories

The following sections describe the various directories that are a part of any Nexus installation. When you install Nexus Open Source or Nexus Professional, you are creating two directories: a directory which contains the Nexus runtime and application, and a directory which contains your own configuration and data. When you upgrade to a newer version of Nexus, you replace the Nexus application directory and retain all of your own custom configuration and repository data in sonatype-work/

Sonatype Nexus Work Directory

The Sonatype Work directory is installed as a sibling to the nexus application directory, and the location of this directory can be configured via the plexus.properties file which is described in <xref linkend="sect-installing-conf-dir" />. <xref linkend="fig-installing_work-dir" /> shows the Sonatype Nexus work directory with the conf/

figs/web/installing_work-dir.png
Figure 11. The Sonatype Nexus Work Directory

The Sonatype Nexus work directory contains the following subdirectories:

backup/

If you have configured a scheduled job to backup Nexus configuration, this directory is going to contain a number of ZIP archives that contain snapshots of Nexus configuration. Each ZIP file contains the contents of the conf/ directory. (Automated backups are a feature of Nexus Professional.)

conf/

This directory contains the Nexus configuration. Settings that define the list of Nexus repositories, the logging configuration, the staging and procurement configuration, and the security settings are all captured in this directory.

indexer/

Contains a Nexus index for all repositories and repository groups managed by Nexus. A Nexus index is a Lucene index which is the standard for indexing and searching a Maven repository. Nexus maintains a local index for all repositories, and can also download a Nexus index from remote repositories.

logs/

The nexus.log file that contains information about a running instance of Nexus. This directory also contains archived copies of Nexus log files. Nexus log files are rotated every day. To reclaim disk space, you can delete old log files from the logs/

p2/

If you are using the P2 repository management features of Nexus Professional, this directory contains a local cache of P2 repository artifacts.

proxy/

Stores data about the files contained in a remote repository. Each proxy repository has a subdirectory in the proxy/attributes/ directory and every file that Nexus has interacted with in the remote repository has an XML file which captures such data as the: last requested timestamp, the remote URL for a particular file, the length of the file, and the digests for a particular file among other things. If you need to backup the local cached contents of a proxy repository, you should also back up the contents of the proxy repository’s directory under proxy/attributes/

storage/

Stores artifacts and metadata for Nexus repositories. Each repository is a subdirectory which contains the artifacts in a repository. If the repository is a proxy repository, the storage directory will contain locally cached artifacts from the remote repository. If the repository is a hosted repository, the storage directory will contain all artifacts in the repository. If you need to backup the contents of a repository, you should backup the contents of the storage directory.

template-store/

Contains templates for default repositories. If you examine the XML files in this directory, you will see that they contain default templates for each different type of repository. For example, the repository-default_proxy_release.xml file contains defaults for a Proxy repository with a release policy.

timeline/

Contains an index which Nexus uses to store events and other information to support internal operations. Nexus uses this index to store feeds and history.

trash/

If you have configured scheduled jobs to remove snapshot artifacts or to delete other information from repositories, the deleted data will be stored in this directory. To empty this trash folder, view a list of Nexus repositories, and then click on the Trash icon in the Nexus user interface.

The conf/ directory contains a number of files which allow for configuration and customization of Nexus. All of the files contained in this directory are altered by the Nexus administrative user interface. While you can change the configuration settings contained in these files with a text editor, Sonatype recommends that you modify the contents of these files using the Nexus administrative user interface.

log4j.properties

Contains Log4J configuration, if you need to customize the detail of log messages, the frequency of log file rotation, or if you want to connect your own, custom Log4J appenders, you would alter this configuration file.

lvo-plugin.xml

Contains configuration for the latest version plugin. This XML file contains the location of the properties file which Nexus queries to check for a newer version of Nexus.

nexus.xml

The bulk of the configuration of Nexus is contained in this file. This file maintains a list of repositories, and all server-wide configuration like the SMTP settings, security realms, repository groups, targets, and path mappings.

pgp.xml

Contains PGP key server configuration.

nexus-obr-plugin.properties

Contains configuration for the Nexus OSGi Bundle repository plugin in Nexus Professional.

procurement.xml

Contains configuration for the Nexus Procurement plugin in Nexus Professional.

security.xml

Contains security information about users and roles in Nexus.

staging.xml

Contains configuration for the Nexus Staging plugin in Nexus Professional.

Nexus Configuration Directory

After installing Nexus Professional, you will have a nexus-professional-webapp-${nexus.version}/ directory and a sonatype-work/ directory, and after installing Nexus Open Source, you will have a nexus-webapp-${nexus.version}/ directory and a sonatype-work/ directory. This section details the contents of the conf directory that is shown in <xref linkend="fig-installing_conf-dir" />. This directory contains configuration for the Jetty servlet container. You will only need to modify the files in this directory if you are customizing the configuration of <indexterm> <primary>Plexus <primary>Jetty Jetty servlet container, or the behavior of the scripts that start Nexus.

figs/web/installing_conf-dir.png
Figure 12. Nexus Professional Configuration Directory

The files and folders contained in this directory are:

classworlds.conf

Defines the order in which resources and classes are loaded from the classpath. It is unlikely that even the most advanced Nexus users will ever need to customize the contents of this file.

plexus.properties

This file contains configuration variables which control the behavior of Plexus and the Jetty servlet container. If you are customizing the port and host that Nexus will listen to, you would change the application-port and application-host properties defined in this file. If you wanted to customize the location of the Sonatype work directory, you would modify the value of the nexus-work property in this configuration file.

plexus.xml

Defines the class names and configuration of components which are loaded by Plexus at startup. This file should never be changed as all configurable values have been removed from this file and placed in plexus.properties

jetty.xml

If this file is present in the conf/ directory, it will be used to configure Jetty.

The conf/examples/ directory contains sample Jetty configuration files which can be used to customize the behavior of the Jetty servlet container:

jetty.xml

contains a jetty.xml sample with no customizations. This plexus.properties

jetty-ajp.xml

Contains a jetty.xml sample which will configure Nexus to listen on an AJP port 8009. This configuration can be used if you are proxying your Nexus server with web server which understands the AJP protocol such as Apache httpd with the mod_proxy_ajp module.

jetty-dual-ports-with-ssl.xml

Contains a jetty.xml sample which sample configuration also contains the SSL redirect rule.

jetty-faster-windows.xml

Contains a jetty.xml sample which configures a response buffer size that will address performance issues on Windows 2003 Server, for more information about this fix see <ulink url="http://docs.codehaus.org/display/JETTY/Slow+Win2003">the Jetty Wiki

jetty-header-buffer.xml

Contains a jetty.xml sample which increases the headerBufferSize to 8k from the default of 4k. Documentation about the header buffer size can be found on <ulink url="http://docs.codehaus.org/display/JETTY/Configuring+Connector">the Jetty Wiki

jetty-simple-https-proxy.xml

Contains a jetty.xml sample which should be used if you are proxying a Nexus instance with a web server that is handling SSL. For example, if you were proxying Nexus with Apache httpd server using mod_ssl you would use this configuration to configure the Jetty RewriteHandler

jetty-ssl.xml

Contains a jetty.xml sample which will only serve SSL plexus.properties

The conf/examples/proxy-https/ directory contains two files: apache2.conf and jetty.xml contains sample mod_proxy directives to configure Apache httpd to handle SSL.

Configuring Maven to Use Nexus

Introduction

To use Nexus, you will configure Maven to check Nexus instead of the public repositories. To do this, you’ll need to edit your mirror settings in your <filename>~/.m2/settings.xml file. First, we’re going to demonstrate how to configure Maven to consult your Nexus installation instead of retrieving artifacts directly from the Maven Central repository. After we override the central repository and demonstrate that Nexus is working, we’ll circle back to provide a more sensible set of settings that will cover both releases and snapshots.

Configuring Maven to Use a Single Nexus Group

If you are adopting Nexus for internal development you should configure a single Nexus group which contains both releases and snapshots. To do this, add snapshot repositories to your public group, and add the following mirror configuration to your Maven settings in ~/.m2/settings.xml

Configuring Maven to Use a Single Nexus Group
<settings>
  <mirrors>
    <mirror>
      <!--This sends everything else to /public -->
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/nexus/content/groups/public</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>nexus</id>
      <!--Enable snapshots for the built in central repo to direct -->
      <!--all requests to nexus via the mirror -->
      <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
     <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <!--make the profile active all the time -->
    <activeProfile>nexus</activeProfile>
  </activeProfiles>
</settings>

In <xref linkend="ex-maven-nexus-simple" /> we have defined a single profile: nexus profile is configured to download from the central repository with a bogus URL. This URL is overridden by the mirror setting in the same settings.xml file to point to the URL of your single Nexus group. The nexus group is then listed as an active profile in the <sgmltag>activeProfiles element.

Adding Custom Repositories for Missing Dependencies

If you’ve configured your Maven settings.xml to list the Nexus public group as a mirror for all repositories, you might encounter projects which are unable to retrieve artifacts from your local Nexus installation. This usually happens because you are trying to build a project which has defined a custom set of repositories and snapshotRepositories in a pom.xml. When you encounter a project which contains a custom repository element in a pom.xml add this repository to Nexus as a new proxy repository and then add the new proxy repository to the public group.

Adding a New Repository

To add a repository, log into Nexus as an Administrator, and click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Clicking on this link should bring up a window that lists all of the repositories which Nexus knows about. You’ll then want to create a new proxy repository. To do this, click on the Add link that is directly above the list of repositories. When you click the Add button, click the down arrow directly to the right of the word Add, this will show a drop-down which has the options: Hosted Repository, Proxy Repository, Virtual Repository, and Repository Group. Since you are creating a proxy repository, click on Proxy Repository.

figs/web/repository-manager_add-repository-dropdown.png
Figure 13. Creating a New Nexus Proxy Repository

Once you do this, you will see a screen resembling <xref linkend="fig-add-repo" />. Populate the required fields Repository ID and the Repository Name with "caja" and "Google Caja". Set the Repository Policy to "Release", and the Remote Storage Location to http://google-caja.googlecode.com/svn/maven

figs/web/repository-manager_add-repository.png
Figure 14. Adding a Nexus Repository

Once you’ve filled out this screen, click on the Save button. Nexus will then be configured with the caja proxy repository. Do the same thing for the oauth repository. Create a repository with the Repository ID of oauth, with a Release policy, and the Remote Storage Location of http://oauth.googlecode.com/svn/code/maven

Adding a Repository to a Group

Next you will need to add both of these new repositories to the public Nexus Group. To do this, click on the Repositories link in the left-hand navigation menu in the Views/Repositories section. Nexus lists Groups and Repositories in the same list so click on the public group. After clicking on the public group, you should see the Browse and Configuration tabs in the lower half of the Nexus window.

Note If you click on a repository or a group in the Repositories list and you do not see the Configuration tab, this is because your Nexus user does not have administrative privileges. To perform the configuration tasks outlined in this chapter, you will need to be logged in as a user with administrative privileges.

Clicking on the Configuration tab will bring up a screen which looks like <xref linkend="fig-add-to-group" />.

figs/web/repository-manager_add-to-group.png
Figure 15. Adding New Repositories to a Nexus Group

To add the two new repositories to the public Nexus Group, find the repositories in the Available Repositories list on the right, click on the repository you want to add and drag it to the left to the Ordered Group Repositories list. Once the repository is in the Ordered Group Repositories list you can click and drag the repository within that list to alter the order in which a repository will be searched for a matching artifact. Once the Google Caja and Google OAuth project repositories are added to the public Nexus Group, you should be able to build Apache Shindig and watch Maven download the Caja and OAuth artifacts from the respective repositories.

Note Nexus makes use of an interesting Javascript widget library named ExtJS. ExtJS provides for a number of interesting UI widgets that allow for rich interaction like the drag-drop UI for adding repositories to a group and reordering the contents of a group.

In the last few sections, you encountered a situation where you needed to add two custom repositories to a build in order to download two libraries (Google Caja and Google OAuth) which are not available in the Maven Central repository. If you were not using a repository manager, you would have added these repositories to the repository element of your project’s POM, or you would have asked all of your developers to modify ~/.m2/settings.xml to reference two new repositories. Instead, you used the Nexus repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group in Nexus, you can freely swap in new repositories without asking your developers to change local configuration, and you’ve gained a certain amount of control over which repositories are made available to your development team.

Using Nexus

Introduction

Nexus provides for anonymous access for users who only need to search repositories, browse repositories, and peruse the system feeds. This anonymous access level changes the navigation menu and some of the options available when you right-click on a repository. This read-only access displays a user interface shown in <xref linkend="fig-repoman-anonymous-interface" />.

figs/web/repository-manager_public-interface.png
Figure 16. Nexus Interface for Anonymous Users

Browsing Repositories

One of the most straightforward uses of the Nexus is to browse the structure of a Maven repository. If you click on the Browse Repositories menu item in the Views menu, you should see the following display. The top-half of <xref linkend="fig-nexus-browse-repo" /> shows you a list of groups and repositories along with the type of the repository and the repository status. To browse the artifacts that are stored in a local Nexus instance, click on the Browse Storage tab for a repository as shown in <xref linkend="fig-nexus-browse-repo" />.

figs/web/repository-manager_browse-repositories.png
Figure 17. Browsing a Nexus Repository

When you are browsing a repository, you can right click on any file and download it directly to your browser. This allows you to retrieve specific artifacts manually, or examine a <acronym>POM file in the browser.

Note When browsing a remote repository you might notice that the tree doesn’t contain all of the artifacts in a repository. When you browse a proxy repository, Nexus is displaying the artifacts which have been cached locally from the remote repository. If you don’t see an artifact you expected to see through Nexus, it only means that Nexus has yet to cache the artifact locally. If you have enabled remote repository index downloads, Nexus will return search results that may include artifacts not yet downloaded from the remote repository. <xref linkend="fig-nexus-browse-repo" />, is just an example, and you may or may not have the <varname>doxia-core artifact available in your installation of Nexus.

A Nexus proxy repository acts as a local cache for a remote repository, in addition to downloading and caching artifacts locally, Nexus will also download an index of all the artifacts stored in a particular repository. When searching or browsing for artifacts, it is often more useful to search and browse the repository index. To view the repository index, click on the Browse Index tab for a particular repository to load the interface shown in <xref linkend="fig-nexus-browse-repo-index" />.

figs/web/repository-manager_browse-repository-index.png
Figure 18. Browsing a Nexus Repository Index

As shown in <xref linkend="fig-nexus-browse-repo-index" />, if an artifact has been downloaded from a remote repository and cached in Nexus, the artifact or folder will display a small Nexus logo.

View Artifact Dependencies

Nexus Professional provides you with the ability to browse an artifact’s dependencies. Using the artifact metadata found in an artifact’s POM, Nexus will scan a repository or a repository group and attempt to resolve and display an artifact’s dependencies. To view an artifact’s dependencies, browse the repository storage or the repository index, select an artifact (or an artifact’s POM), and then click on the Maven Dependency tab.

On the Maven Dependency tab, you will see the following form elements:

Repository

When resolving an artifact’s dependencies, Nexus will query an existing repository or repository group. In many cases it will make sense to select the same repository group you are referencing in your Maven Settings. If you encounter any problems during the dependency resolution, you need to make sure that you are referencing a repository or a group which contains these dependencies.

Mode

An artifact’s dependencies can be list as either a tree or a list. When dependencies are displayed in a tree, you can inspect direct dependencies and transitive dependencies. This can come in handy if you are assessing an artifact based on the dependencies it is going to pull into your project’s build. When you list dependencies as a list, Nexus is going to perform the same process used by Maven to collapse a tree of dependencies into a list of dependencies using rules to merge and override dependency versions if there are any overlaps or conflicts.

Once you have selected a repository to resolve against and a mode to display an artifact’s dependencies, click on the Resolve button as shown in <xref linkend="fig-using-dependencies" />. Clicking on this button will start the process of resolving dependencies, depending on the number of artifacts already cached by Nexus, this process can take anywhere from a few seconds to minute. Once the resolution process is finished, you should see the artifact’s dependencies as shown in <xref linkend="fig-using-dependencies" />.

figs/web/using_dependencies.png
Figure 19. View an Artifact’s Dependencies

Once you have resolved an artifact’s dependencies, you can double click on a row in the tree or list of dependencies to navigate to other artifacts within the Nexus interface.

Viewing Artifact Metadata

Nexus Professional gives you the ability to view artifact metadata. When browsing repository storage or a repository index, clicking on an artifact will load the Artifact Information panel. Selecting the Artifact Metadata tab will display the interface shown in <xref linkend="fig-using-viewing-metadata" />.

figs/web/meta_existing-meta-value.png
Figure 20. Viewing Artifact Metadata

Artifact metadata consists of a key, a value, and a namespace. Existing metadata from an artifact’s POM is given a urn:maven namespace, and custom attributes are stored under the urn:nexus/user namespace.

Editing Artifact Metadata

Nexus Professional gives you the ability to add custom attributes to artifact metadata. To add a custom attribute, click on an artifact in Nexus, and select the Artifact Metadata tab. On the Artifact Metadata tab, click on the Add… button and a new row will be inserted into the list of attributes. Supply a key and value and click the Save button to update an artifact’s metadata. <xref linkend="fig-using-editing-metadata" /> shows the Artifact Metadata panel with two custom attributes: "approvedBy" and "approved".

figs/web/meta_setting-meta-value.png
Figure 21. Editing Artifact Metadata

Browsing Groups

Nexus contains ordered groups of repositories which allow you to expose a series of repositories through a single URL. More often than not, an organization is going to point Maven at the two default Nexus groups: Public Repositories and Public Snapshot Repositories. Most end-users of Nexus are not going to know what artifacts are being served from what specific repository, and they are going to want to be able to browse the Public Repository. To support this use case, Maven allows you to browse the contents of a Nexus Group as if it were a single merged repository with a tree structure. <xref linkend="fig-nexus-browse-group" />, shows the browsing storage interface for a Nexus Group. There is no difference to the user experience of browsing a Nexus Group vs. browsing a Nexus Repository.

figs/web/repository-manager_browse-group.png
Figure 22. Browsing a Nexus Group

When browsing a Nexus group’s storage, you are browsing the underlying storage for all of the repositories which are contained in a group. If a Nexus group contains proxy repositories, the Browse Storage tab will show all of the artifacts in the Nexus group that have been download from the remote repositories. To browse and search all artifacts available in a Nexus group, click on the Browse Index tab to load the interface shown in <xref linkend="fig-nexus-browse-group-index" />.

figs/web/repository-manager_browse-group-index.png
Figure 23. Browsing a Nexus Group Index

Searching for Artifacts

In the left-hand navigation area, there is an Artifact Search text field next to a magnifying glass. To search for an artifact by groupId or artifactId, type in some text and click the magnifying glass. Typing in the search term "guice" and clicking the magnifying glass should yield a search result similar to <xref linkend="fig-nexus-search" />.

figs/web/search-results.png
Figure 24. Results of an Artifact Search for "guice"

Once you’ve located the artifact you were looking for you can click on the pom link to download the POM or the artifact link to download the artifact.

  • Look at the Version column in the search results. In this version of the search interface, we decided to list the most recent version. If you need to view a different version, click on "Show All Versions". Clicking on "Show All Versions" will drill down into the list of available versions.

  • Look at the Download column in the search results. This Download column contains direct download links for the most recent version of the artifact. To download a matching artifact, just click on a link in this column.

  • Select a search result, and you will see the artifact in the Repository Tree in the lower left-hand quadrant of this interface. This is helpful to give you context for an artifact. An artifact could be present in more than one repository. If this is the case, click on the value next to "Viewing Repository" to switch between multiple matching repositories.

  • In the lower right-hand quadrant of the interface, you will see a number of tabs which show information about the selected search result:

    • Maven Information: This contains basic identifiers and a snippet of XML you can use to add this artifact as a project dependency.

    • Archive Browser (Nexus Professional): This gives you a way to explore the contents of an archive in the repository. You can view the files and folders contained in a matching search result.

    • Artifact Information: This tab contains timestampes, file size, checksum values, and a list of repositories containing a given artifact.

    • Artifact Metadata (Nexus Professional): This tab shows all of the built-in and custom metadata associated with an artifact.

In addition to searching by a groupId or an artifactId, Nexus has a feature which allows you to search for an artifact by a checksum.

Warning Let me guess? You installed Nexus, ran to the search box, typed in the name of a group or an artifact, pressed search, and saw absolutely nothing. No results. Nexus isn’t going to retrieve the remote repository indexes by default, you need to activate downloading of remote indexes for the three proxy repositories that Nexus ships with. Without these indexes, Nexus has nothing to search. Find instructions for activating index downloads in <xref linkend="config-sect-manage-repo" />.

Nexus OpenSearch Integration

OpenSearch a standard which facilitates searching directly from your browser’s search box. If you are using Internet Explorer 7+ or Firefox 2+ you can add any Nexus instance as an OpenSearch provider. Then you can just type in a search term into your browser’s search field and quickly search for Maven artifacts. To configure OpenSearch, load Nexus in a browser and then click on the dropdown next to the search tool that is embedded in your browser. <xref linkend="fig-using-opensearch-configure" /> shows the Add Nexus option that is present in Firefox’s OpenSearch provider dropdown.

figs/web/using_opensearch-config.png
Figure 25. Configuring Nexus as an OpenSearch Provider

Once you have added Nexus to the list of OpenSearch providers, click on the dropdown next to the search term and select Nexus (localhost) from the list of OpenSearch providers. Type in a groupId, artifactId, or portion of a Maven identifier and press enter. Your opensearch-friendly web browser will then take you to the search results page of Nexus displaying all the artifacts that match your search term.

figs/web/using_opensearch-search.png
Figure 26. OpenSearch Search Results in Nexus

Once, you have configured your browser to use Nexus as an OpenSearch provider, searching for a Maven artifact is as simple as typing in a groupId or artifactId, selecting Nexus from the dropdown shown in <xref linkend="fig-using-permanent-opensearch-option" />, and performing a search.

figs/web/using_opensearch-permanent.png
Figure 27. Nexus Available as an Option in the Firefox OpenSearch Provider List

Searching Artifact Metadata

Nexus Professional provides you with the ability to configure custom artifact metadata and search for artifacts with specific metadata. To search for artifacts using metadata, click on the Advanced Search link directly below the search field in the Nexus application menu to open the Search panel. Once in the search panel, click on the Keyword Search and click on Metadata Search in the search type dropdown as shown in <xref linkend="fig-using-search-metadata" />.

figs/web/meta_search-selection.png
Figure 28. Searching Artifact Metadata

Once you select the Metadata Search you will see two search fields and an operator dropdown. The two search fields are the key and value of the metadata you are searching for. The key corresponds to the key of the metadata you are searching for, and the value contains the value or value range you are searching for. The operator dropdown can be set to Equals, Matches, Bounded, or Not Equal.

figs/web/meta_search-function.png
Figure 29. Metadata Search Results for Custom Metadata

Once you locate a matching artfiact in the Metadata Search interface, click on the artifact and then select the Artifact Metadata to examine an artifacts metadata as shown in <xref linkend="fig-using-search-metadata-results" />.

figs/web/meta_search-result-0.png
Figure 30. Metadata Search Results for Custom Metadata

Uploading Artifacts

When your build makes use of proprietary or custom dependencies which are not available from public repositories, you will often need to find a way to make them available to developers in a custom Maven repository. Nexus ships with a preconfigured 3rd Party repository that was designed to hold 3rd Party dependencies which are used in your builds. To upload artifacts to a repository, select a hosted repository in the Repositories panel and then click on the Artifact Upload tab. Clicking on the Artifact Upload tab will display the tab shown in <xref linkend="fig-using-artifact-upload" />.

figs/web/using_artifact-upload.png
Figure 31. Artifact Upload Form

To upload an artifact, click on Select Artifact(s) for Upload… and select one or more artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Once you have clicked on the Add Artifact button, you can then configure the source of the Group, Artifact, Version (GAV) parameters. If the artifact you are uploading is a JAR file that was created by Maven it will already have POM information embedded in it. If you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition dropdown at the top of this form. Selecting GAV Parameters will expose a set of form fields which will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file associated with the uploaded artifact, select From POM in the GAV Definition dropdown. Selecting From POM in this dropdown will expose a button labeled "Select POM to Upload". Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Artifact Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times.

Browsing System Feeds

Nexus provides feeds that capture system events, you can browse these feeds by clicking on System Feeds under the View menu. Clicking on System Feeds will show the panel in <xref linkend="fig-repoman-system-feeds" />. You can use these simple interface to browse the most recent reports of artifact deployments, cached artifacts, broken artifacts, and storage changes that have occurred in Nexus.

figs/web/repository-manager_system-feed.png
Figure 32. Browsing Nexus System Feeds

These feeds can come in handy if you are working at a large organization with multiple development teams deploying to the same instance of Nexus. If such an arrangement, all developers in an organization can subscribe to the RSS feeds for New Deployed Artifacts as a way to ensure that everyone is aware when a new release has been pushed to Nexus. Exposing these system events as RSS feeds also opens to the door to other, more creative uses of this information, such as connecting Nexus to external automated testing systems. To access the RSS feeds for a specific feed, select the feed in the System Feeds view panel and then click on the Subscribe button. Nexus will then load the RSS feed in your browse and you can subscribe to the feed in your favorite RSS

There are six system feeds available in the System Feeds view, and each has a URL which resembles the following URL

http://localhost:8081/nexus/service/local/feeds/recentlyChangedFiles

Where recentChanges would be replaced with the identifier of the feed you were attempting to read. Available system feeds include:

Table 1. Available System Feeds
Feed Identifier Description

systemRepositoryStatusChanges

Automatic or User-initiated status changes (out-of-service and blocked proxies)

systemChanges

authcAuthz

Authentication and Authorization Events

brokenArtifacts

Broken Artifacts (Checksum mismatch, missing checksums, invalid POMs)

brokenFiles

Broken Files (Checksum errors.)

errorWarning

Errors, warnings, and exceptions from Nexus

recentlyCachedOrDeployedArtifacts

New artifacts in all repositories (cached or deployed)

recentlyCachedOrDeployedFiles

New files in all repositories (cached or deployed)

recentlyCachedArtifacts

New cached artifacts in all repositories

recentlyCachedFiles

New cached files in all repositories

recentlyDeployedArtifacts

New deployed artifacts in all repositories

recentlyDeployedFiles

New deployed files in all repositories

recentlyChangedArtifacts

Changed artifacts in all repositories

recentlyChangedFiles

Changed files in all repositories

Log Files and Configuration

The Logs and Config Files link is only visible to Administrative users under the Views menu. Click on this option brings up the dialog shown in <xref linkend="fig-nexus-logs" />. From this screen you can view the following log and configuration files by clicking on the drop down selection next to the Download button.

nexus.log

Think of this as the general application log for Nexus. Unless you are an administrative user, you might not have must interest in the information in this log. If you are trying to debug an error, or if you have uncovered a bug in Nexus, you’ll use this log viewer to diagnose problems with Nexus.

nexus.xml

This XML file contains most of the configuration data for your instance of Nexus. It is stored in

log4j.properties

This file controls the logging facility of Nexus using the standard Log4J property file syntax. To edit the format or level of the Log4J logging, click on Log under the Administration menu. For more information about configuring the Nexus Log, see <xref linkend="configuring-sect-log" />.

security.xml

This XML file contains the configuration for the XmlAuthenticatingRealm and the XmlAuthorizingRealm. It contains built-in user definitions and any externally mapped users that are mapped to Nexus roles.

figs/web/repository-manager_log-file.png
Figure 33. Browsing Nexus Logs and Configuration

If you are running Nexus Professional, you should see a few more configuration files in this directory which will correspond to the Procurement and Staging suites. The configuration files specific to Nexus Professional are:

procurement.xml

This file contains the configuration for the Nexus Procurement Suite as described in <xref linkend="procure" />.

staging.xml

This file contains the configuration for the Staging Suite as described in <xref linkend="staging" />.

In <xref linkend="fig-nexus-logs" /> there is a "tail" checkbox. If this box is checked, then Nexus will always show you the end of a log file. This can come in handy if you want to see a continuously updated log file. When this tail box is checked, a dropdown at the bottom of the panel allows you to set the update frequency. The contents of this dropdown are shown in <xref linkend="fig-using-update-freq" />. If an update interval is selected, Nexus will periodically refresh the selected log file.

figs/web/using_tail-frequency.png
Figure 34. Selecting the Update Frequency when Tailing a Log File

Changing Your Password

If you have the appropriate security privilege, you will see an option to change your password in the left-hand side of the browser. To change your password, click on change password, supply your current password, and choose a new password. When you click on Change Password, your Nexus password will be changed.

figs/web/repository-manager_change-password.png
Figure 35. Changing Your Nexus Password

Filing a Problem Report

If you encounter a problem with Nexus, you can use the Nexus UI to report a bug or file an issue against the Nexus project in Sonatype’s JIRA instance. To file a problem report, you will first need to sign up for an account on http://issues.sonatype.org. In Nexus 1.6, you can click on "File Issue" in the Nexus menu, supply your Sonatype JIRA credentials, and file a problem report. Supply your JIRA username and password along with a short title and a description as shown in the following figure. When you file a Nexus problem report, Nexus will create a new issue in JIRA and attach your configuration and logs to the newly filed issue.

figs/web/configuring-generate-report.png
Figure 36. Generating a Nexus Problem Report

Configuring Nexus

Configuring Nexus

Many of the configuration screens shown in this section are only available to administrative users. Nexus allows the admin user to customize the list of repositories, create repository groups, customize server settings, and create routes or "rules" that Maven will use to include or exclude artifacts from a repository.

Customizing Server Configuration

In a production installation of Nexus, you’ll probably want to customize the administrative password to something other than "admin123", and you might want to override the default directories that Nexus uses to store repository data. To do this, log in as the administrative user and click on Server under Configuration in the left-hand navigation menu. The server configuration screen is shown in <xref linkend="fig-nexus-server-config" /> and <xref linkend="fig-nexus-server-config-2" />.

figs/web/repository-manager_server-settings.png
Figure 37. Nexus Server Configuration (File, SMTP, and HTTP Config)
figs/web/repository-manager_server-settings-2.png
Figure 38. Nexus Server Configuration (Security Settings, Anonymous Access)
figs/web/repository-manager_server-settings-3.png
Figure 39. Nexus Server Configuration (App Server and HTTP Proxy Config)
figs/web/configuring_pgp-keyserver.png
Figure 40. Configuring PGP Keyserver Preferences

This screen allows you to change:

SMTP Settings

Nexus sends email to users who need to recover usernames and password. To do this, you’ll need to configure the SMTP server settings in this dialog. This section of the form takes an SMTP Host and Port as well as other parameters relating to SMTP authentication and encryption. You can also change the From: header of an email from Nexus.

User Agent

This is the identifier which Nexus uses when it is making an HTTP request. You may want to change this if Nexus needs to use an HTTP Proxy, and the Proxy will only work if the User Agent is set to a specific value.

Additional URL

This is a list of extra parameters to place on a GET request to a remote repository. You could use this to add identifying information to requests.

Request Timeout

The amount of time Nexus will wait for a request to succeed when interacting with an external, remote repository.

Request Retry Attempts

The number of times Nexus will retry a failed HTTP

Security Settings

You can choose to enable or disable security, enable or disable anonymous access, and set the username and password for anonymous access. If you choose to enable security, you are telling Nexus to enforce role-based access control to enforce read and write access to repositories.

The anonymous username and password is used to integrate with other realms that may need a special username for anonymous access. In other words, the username and password here is what we attempt to authorize when someone makes an anonymous request. You would change the anonymous username to “guest” if you wanted to integrate Nexus with Microsoft’s Active Directory.

Application Server Settings

This section allows you to change the Base URL for your Nexus installation. It is used when generating links in emails and RSS feeds. The Sonatype Nexus repository is available on http://respository.sonatype.org, and it makes use of this Base URL field to ensure that links in emails and RSS feeds point to the correct URL. If you are hosting Nexus behind a proxy server and you want to make sure that Nexus always uses the specified Base URL, check the "Force Base URL" checkbox. If the Force Base URL is not checked, Nexus will craft URLs in HTTP responses based on the request URL, but it will use the Base URL when it is generating emails.

HTTP Proxy Settings

There are a number of HTTP Proxy settings for Nexus installations which need to be configured to use an HTTP Proxy. You can specify a host, port, and a number of authentication options which might be required by your proxy server.

PGP Key Server Information

Nexus Professional uses a PGP Key Server to retrieve PGP keys when validating artifact signatures. To add a new Key Server URL, enter the URL in the Key Server URL field and click on the Add button. To remove a Key Server URL, click on the URL you wish to remove from the list and click on the Remove button. Key Servers are consulted in the order that they are listed in the Key Server URLs list, to reorder your Key Server URLs, click and drag a URL in the Key Server URLs list.

Configuring Automated Error Reporting Settings

Nexus can be configured to automatically file exception and error reports with the Nexus project in the Sonatype issue tracker. Activating this setting in your own Nexus installation helps to improve Nexus as the development team will receive automatic error reports if your Nexus instance experiences an error or a failure. The Nexus Server configuration’s Automated Error Reporting Settings section is shown in <xref linkend="fig-configuring-automated-error" />. This section accepts a JIRA username and password, and allows you to configure Nexus to use the default HTTP Proxy Settings when Nexus attempts to file an error report with the Sonatype issue tracker.

figs/web/configuring_automated-error.png
Figure 41. Configuring the Automated Error Reporting

To sign up for an account on the Sonatype JIRA instance, go to http://issues.sonatype.org. Once you see the website shown in <xref linkend="fig-configuring-sonatype-jira" />, click on the "Signup" link below the Login form.

figs/web/configuring_automated-error-jira-home.png
Figure 42. Sonatype Issue Tracker

Fill out the signup form shown in <xref linkend="fig-configuring-sonatype-jira-signup" />, and choose a username and password. This is the username and password you should use in the Automated Error Reporting Settings section of the Server configuration shown in <xref linkend="fig-configuring-automated-error" />.

figs/web/configuring_automated-error-jira-signup.png
Figure 43. Signing Up for a Sonatype Issue Tracker Account

New Version Notification

Nexus can notify you of new versions of Nexus via the Nexus interface. To enable this feature, check the Enable checkbox in the New Version Notification section of the Nexus server settings as shown in <xref linkend="fig-configuring-new-version" />.

figs/web/configuring_new-version.png
Figure 44. New Version Notification Settings

Managing Repositories

To manage Nexus repositories, log in as the administrative user and click on Repositories in the Views/Repositories menu in the left-hand navigation menu. If you are logged into Nexus as a user with administrative privileges, you will see Configuration and Mirrors tabs in the lower portion of the Nexus window.

Nexus provides for three different kinds of repositories:

Proxy Repository

A proxy repository is a proxy of a remote repository. By default, Nexus ships with the following configured proxy repositories:

Apache Snapshots

This repository contains snapshot releases from the Apache Software Foundation http://people.apache.org/repo/m2-snapshot-repository

Codehaus Snapshots

This repository contains snapshot released from Codehaus http://snapshots.repository.codehaus.org/

Maven Central Repository

This is the central repository (for releases). http://repo1.maven.org/maven2/

Hosted Repository

A hosted repository is a repository which is hosted by Nexus. Maven ships with the following configured hosted repositories:

3rd Party

This hosted repository should be used for third-party dependencies not available in the public Maven repositories. Examples of these dependencies could be commercial, proprietary libraries such as an Oracle JDBC driver that may be referenced by your organization.

Releases

This hosted repository is where your organization will publish internal releases.

Snapshots

This hosted repository is where your organization will publish internal snapshots.

Virtual Repository

This serves as an adapter to and from different types of repositories. Currently Nexus supports conversion to and from Maven 1 repositories and Maven 2 repositories.

figs/web/repository-manager_repository-config.png
Figure 45. Repository Configuration Screen for a Proxy Repository
figs/web/repository-manager_repository-config-2.png
Figure 46. Repository Configuration Screen for a Proxy Repository
figs/web/repository-manager_repository-config-3.png
Figure 47. Proxy Configuration Access Settings for a Hosted Repository

<xref linkend="fig-repo-config" /> shows the Repository configuration screen for a Proxy repository in Nexus. From this screen, you can manage the settings for proxying an external repository. From this screen, you can configure:

Repository ID

The repository ID is the identifier which will be used in the Nexus URL. For example, the central proxy repository has an ID of "central", this means that maven can access the repository directly at http://localhost:8081/nexus/content/repositories/central. The Repository ID must be unique in a given Nexus installation. ID is required.

Repository Name

The display name for a repository. Name is required.

Repository Type

The type of repository (proxy, hosted, or virtual). You can’t change the type of a repository, it is selected when you create a repository.

Repository Policy

If a proxy repository has a policy of release than it will only access released versions from the remote repository. If a proxy repository has a policy of snapshot, it will download snapshots from the remote repository.

Default Storage Location

Not editable, shown for reference. This is the default storage location for the local cached contents of the repository.

Override Storage Location

You can choose to override the storage location for a specific repository. You would do this if you were concerned about storage and wanted to put the contents of a specific repository (such as central) in a different location.

Remote Repository Access

This section tells Nexus where to look for and how to interact with the remote Maven repository being proxied.

Remote Storage Location

This is the URL of the remote Maven repository.

Download Remote Indexes (Not shown in figure)

This field controls the downloading of the remote indexes. Currently only central has an index at http://repo1.maven.org/maven2/.index.

If enabled, Nexus will download the index and use that for its searches as well as serve that up to any clients which ask for the index (like m2eclipse). The default for new proxy repositories is enabled, but all of the default repositories included in Nexus have this option disabled. To change this setting for one of the proxy repositories that ship with Nexus, change the option, save the repository, and then re-index the repository. Once this is done, artifact search will return every artifact available on the Maven Central repository.

Auto blocking active

If Auto blocking active is set to true, Nexus will automatically block a proxy repository if the remote repository becomes unavailable. While a proxy repository is blocked, artifacts will still be served to clients from a local cache, but Nexus will not attempt to locate an artifact in a remote repository. Nexus will periodically retest the remote repository and unblock the repository once it becomes available.

File content validation (Not shown in figure)

If set to true, Nexus will perform a lightweight check on the content of downloaded files. This will prevent invalid content to be stored and proxied by Nexus, which otherwise can happen in cases where the remote repository (or some proxy between Nexus and the remote repository) for example returns an html page instead of the requested file.

Checksum Policy

Sets the checksum policy for a remote repository. This option is set to Warn by default. The possible values of this setting are:

  • Ignore - Ignore the checksums entirely

  • Warn - Print a warning in the log if a checksum is not correct

  • StrictIfExists - Refuse to cache an artifact if the calculated checksum is inconsistent with a checksum in the repository. Only perform this check if the checksum file is present.

  • Strict - Refuse to cache an artifact if the calculated checksum is inconsistent or if there is no checksum for an artifact.

Authentication

This section allows you to set a Username, Password, Private Key, Key Passphrase, NT LAN Host, and NT Lan Manager Domain for a remote repository.

Access Settings

This section configures access settings for a repository.

Deployment Policy

This setting controls how a Hosted repository allows or disallows artifact deployment. If this policy is set to "Read Only", no deployment is allowed. If this policy is set to "Disable Redeploy", a client can only deploy a particular artifact once and any attempt to redeploy an artifact will result in an error. If this policy is set to "Allow Redeploy", clients can deploy artifacts to this repository and overwrite the same artifact in subsequent deployments. This option is visible for Hosted repositories as shown in <xref linkend="fig-repo-config-hosted" />.

Allow File Browsing

When set to true, users can browse the contents of the repository with a web browser.

Include in Search

When set to true, this repository is search when you perform an Artifact Search in Nexus. If this setting is false, the contents of the repository are excluded from a search.

Publish URL

If this property is set to false, the repository will not be published on a URL, and you will not be able to access this repository remotely. You would set this configuration property to false if you want to prevent clients for connecting to this repository directly.

Expiration Settings

Nexus maintains a local cache of artifacts and metadata, you can configure expiration parameters for a proxy repository. The expiration settings are:

Not Found Cache TTL

If Nexus fails to locate an artifact, it will cache this result for a given number of minutes. In other words, if Nexus can’t find an artifact in a remote repository, it will not repeated attempt to resolve this artifact until the Not Found Cache TTL time has been exceeded. The default for this setting is 1440 minutes (or 24 hours).

Artifact Max Age

Tells Nexus when that maximum age of an artifact is before it retrieves a new version from the remote repository. The default for this setting is -1 for a repository with a Release policy and 1440 for a repository with Snapshot policy.

Metadata Max Age

Nexus retrieves metadata from the remote repository. It will only retrieve updates to metadata after the Metadata Max Age has been exceeded. The default value for this setting is 1440 minutes (or 24 hours).

HTTP Request Settings

This section lets you change the properties of the HTTP request to the remote repository. In this section you can configure the User Agent of the request, add parameters to a request, and set the timeout and retry behavior. This section refers to the HTTP request made from Nexus to the remote Maven repository being proxied.

HTTP Proxy Settings

This section lets you configure the HTTP Proxy for the request from Nexus to the remote repository. You can configure a proxy host and port plus an authentication settings you need tell Nexus to use an HTTP Proxy for all requests to a remote repository.

Selecting Mirrors for Proxy Repositories

Nexus also allows you to select which mirrors Nexus will consult for a particular Proxy repository. Clicking on the Mirrors tab will show the figure shown in <xref linkend="fig-configuring-mirror-config" />.

figs/web/repository-manager_config-mirrors.png
Figure 48. Configuring Mirrors for Proxy Repositories

To configure a mirror repository, click on the Mirror URL dropdown and select a mirror for the Proxy repository. Click the Add button, and Nexus will then be configured to download artifacts from the selected mirror. Nexus will always download checksums and metadata from the original (or Canonical) URL for a proxy repository. For example, if Nexus is going to download an artifact, it will retrieve the MD5 checksum from the original Maven Central repository and then retrieve the artifact from the selected mirror.

Adding a Mirror Entry for a Hosted Repository

If you are logged in as a user with Administrative privilege, there will be a Mirrors tab available when you are viewing a Hosted repository, clicking on this Mirrors tab will show the form shown in <xref linkend="fig-configuring-mirrors-hosted" />. This tab contains a list of mirror URLs for this hosted repository. If there are other sites which mirror the contents of this hosted repository, this tab allows you to populate the repository mirror metadata with those URLs.

figs/web/configuring_hosted-mirrors.png
Figure 49. Configuring Mirrors for a Hosted Repository

This repository mirror metadata can then be consumed by other systems that interact with your hosted repository. For example, if you have a release repository which is used by your customers or by the general public, if one of people consuming your Hosted repository is also running a Nexus, they can configure a Proxy repository that targets your Hosted repository and they can use the mirror metadata to configure their instance of Nexus to consume artifacts from mirrors of your Hosted repository.

Viewing Repository Summary Panel

The Repository Summary panel can be loaded by selecting a Hosted, Proxy, or Virtual repository and then clicking on the Summary tab. When viewing the Summary tab of a Hosted repository, as shown in <xref linkend="fig-configuring-summary-hosted" />, you will also see the Distribution Management settings which can be used to configure Maven to publish artifacts to a Hosted repository.

figs/web/repository-manager_summary-hosted.png
Figure 50. Repository Summary Panel for a Hosted Repository

The Repository Summary panel for a Proxy repository, as shown in <xref linkend="fig-configuring-summary-proxy" />, contains all of the repository identifiers and configuration in addition to the size of the local storage for the proxy repository and the URL of the remote repository.

figs/web/repository-manager_summary-proxy.png
Figure 51. Repository Summary Panel for a Proxy Repository

The Repository Summary panel for a Virtual repository, as shown in <xref linkend="fig-configuring-summary-virtual" />, displays repository identifiers and the size of the Virtual repository on disk.

figs/web/repository-manager_summary-virtual.png
Figure 52. Repository Summary Panel for a Virtual Repository

Auto Block/Unblock of Remote Repositories

What happens when Nexus is unable to reach a remote repository? If you’ve defined a proxy repository, and the remote repository is unavailable Nexus will now automatically block the remote repository. Once a repository has been auto-blocked, Nexus will then periodically retest the remote repository and unblock the repository once it becomes available. You can control this behavior by changing the Auto-blocking Active setting under the Remote Repository Access section of the proxy repository configuration as shown in the following figure:

figs/web/configuring_auto-block.png
Figure 53. Configuring Remote Repository Auto Block/Unblock

Managing Groups

Groups are a powerful feature of Nexus, they allow you to combine multiple repositories and other repository groups in a single URL. Nexus ships with two groups: public and public-snapshots. The public group combines the three hosted repositories: 3rd Party, Releases, and Snapshots with the Maven Central repository. The public-snapshots repository combines the Apache Snapshots and Codehaus Snapshots repositories.

In <xref linkend="maven-sect-single-group" /> we configured Maven via the <filename>settings.xml to look for artifacts in the public group managed by Nexus. <xref linkend="fig-group-config" /> shows the group configuration screen in Nexus, in this figure you can see the contents of the public

figs/web/repository-manager_group-config.png
Figure 54. Group Configuration Screen in Nexus

Note that the order of the repositories listed in Order Group Repositories is important. When Nexus searches for an artifact in a group it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the Ordered Group Repositories selection list.

The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved by Maven from a Nexus Repository Group. We recommend placing release repositories higher in the list than snapshot repositories so that LATEST and RELEASE versions are merged appropriately. We also recommend placing repositories with a higher probability of matching the majority of artifacts higher in this list. If most of your artifacts are going to be retrieved from the Maven Central Repository, putting Central higher in this list than a smaller, more focused repository is going to be better for performance as Nexus is not going to interrogate the smaller remote repository for as many missing artifacts.

Managing Routes

Nexus Routes are like filters you can apply to Nexus Groups, they allow you to configure Nexus to include or exclude repositories from a particular artifact search when Nexus is trying to locate an artifact in a Nexus Group. There are a number of different scenarios in which you might configure a route in Nexus, the most common is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want to make sure that you are trying to retrieve your own organization’s artifacts from the hosted Release and Snapshot repositories. Nexus Routes are applicable when you are trying to resolve an artifact from a Nexus Group; using Routes allow you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.

figs/web/repository-manager_route-config.png
Figure 55. Routes Configuration Screen in Nexus

<xref linkend="fig-route-config" /> shows the Route Configuration screen. Clicking on a route will bring up a screen which will allow you to configure the properties of a route. The configuration options available for a route are:

URL Pattern

This is the pattern which Nexus will use to match a request to Nexus. If the regular expression in this pattern is matched, Nexus will either include or exclude the listed repositories from a particular artifact query. In <xref linkend="fig-route-config" /> the two patterns are:

"./(com|org)/somecompany/."

This pattern would match all of the paths which included either "/com/somecompany/" or "/org/somecompany". The expression in the parenthesis matches either com or org, and the ".*" matches one or more characters. You would use a route like this to match your own organization’s artifacts and map these requests to the hosted Nexus Releases and Snapshots repositories.

"./org/some-oss/."

This pattern is used in an exclusive route. It matches every path that contains "/org/some-oss/". This particular exclusive route excludes the local hosted Releases and Snapshots directory for all artifacts which match this path. When Nexus tries to resolve artifacts that match this path, it will exclude the Releases and Snapshots repositories.

Rule Type

Rule Type can be either "inclusive" or "exclusive". An inclusive rule type defines the set of repositories which should be searched for artifacts when the URL pattern has been matched. An exclusive rule type defines repositories which should not be searched for a particular artifact.

Ordered Route Repositories

This is an ordered list of repositories which Nexus will search to locate a particular artifact. Nexus searches top to bottom; if it’s looking for an artifact, it will return the first match. When Nexus is looking for metadata, all repositories in a group are checked and the results are merged. The merging is applied giving preference to the earlier repositories. This is relevant when a project is looking for a LATEST or a RELEASE version. Within a Nexus Group, you should define the release repositories before the snapshot repositories, otherwise LATEST may incorrectly resolve to a snapshot version.

In this figure you can see the two dummy Routes that Nexus has as default routes.

The first route is an inclusive route, it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public Maven repositories like the Maven Central Repository or the Apache Snapshots repository.

The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains "/org/some-oss". This example might make more sense if we replaced "some-oss" with "apache" or "codehaus". If the pattern was "/org/apache", this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.

What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that Nexus Routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a Nexus Group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the Group and the repositories in the inclusive Nexus Route. The order as defined in the Nexus Group will not be affected by the Inclusive routes. Nexus will then take the result of applying the inclusive routes and apply the exclusive routes to this new group. The resulting list is then searched for a matching artifact. One straightforward use of routes is to create a route that excludes the

Maven Central repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding Central from searches for your own artifacts will reduce needless queries to the public repositories.

To summarize, there are creative possibilities with Routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping Routes. Use Routes sparingly, and use course URL patterns, as Nexus evolves there will be more features which allow for more fine grained rules to allow you to prohibit requests for specific artifacts and specific versions of artifacts. Remember that routes are only applied to Nexus Groups, routes are not used when an artifact is requested from a specific repository.

Managing Scheduled Tasks

Nexus allows you to schedule tasks that will be applied to all repositories or to specific repositories on a configurable schedule. You can create the following kinds of scheduled tasks:

Download Indexes

This scheduled task will cause Nexus to download indexes from remote repositories.

Empty Trash

The Evict and Purge actions do not delete data from the Nexus working directory. They simply move data to be cleared or evicted to a trash directory under the Nexus work directory. This service deletes the data in this trash directory.

Evict Unused Proxied Items From Repository Caches

Use it or lose it. This scheduled task tells Nexus to get rid of all proxied items which haven’t been "used" (referenced or retrieved by a client). This can be a good job to run if you are try to conserve storage space. In this service you can specify the number of days over which Nexus will look for activity before making the decision to evict an artifact. (See note about deletion.)

Optimize Repository Index

To speed up searches in Nexus, this task tells the internal search engine to optimize its index files. This has no affect on the indexes published by Nexus. Typically, this task does not have to run more than once a week.

Publish Indexes

Just as Maven downloads an index from a remote repository, Nexus can publish an index in the same format. This will make it easier for people using m2eclipse or Nexus to interact with your repositories.

Purge Nexus Timeline

Nexus maintains a lot of data that relates to the interaction between itself, proxied remote repositories, and clients on Nexus. While this information can be important for purposes of auditing, it can also take up storage space. Using this scheduled task you can tell Nexus to periodically purge this information. (See note about deletion.)

Rebuild Repository Attributes

This scheduled task tells Nexus to walk every file in a repository and gather information like checksums and file contents for every file.

Reindex Repositories

This service tells Nexus to reindex a repository.

Remove Snapshots from a Repository

Often, you will want to remove snapshots from a snapshot repository to preserve storage space. Note that configuring and running this job is not enough to reclaim disk space. You will also need to configure a scheduled job to empty the trash folder. Files are not deleted by the Remove Snapshots job, they are only moved into the Trash folder. When you create a scheduled task to remove snapshots, you can specify: <itemizedlist>

Minimum Snapshots to preserve in a repository - This configuration option allows you to specify a minimum number of SNAPSHOTs to preserve per artifact. For example, if you configured this option with a value of 2, Nexus will always preserve at least two SNAPSHOT artifacts.

Snapshot Retention (in days) - This configuration option allows you to specify the number of days to retain SNAPSHOT artifacts. For example, if you want to make sure that you are always keeping the last three day’s worth of SNAPSHOT artifacts, configure this option with a value of 3.

Whether snapshots should be removed if an artifact has been released - If your Nexus repository also contains a release repository, you can configure Nexus to remove all SNAPSHOT artifacts once an artifact has been released.

Synchronize Shadow Repository

This service synchronizes a shadow (or virtual) repository with its master repository.

Note The Evict and Purge actions do not delete data from the Nexus working directory. They simply move data to be cleared or evicted to a trash directory under the Nexus work directory. If you want to reclaim disk space, you need to clear the Trash on the Browse Repositories screen. If something goes wrong with a evict of clear service, you can move the data back to the appropriate storage location from the trash. You can also schedule the Empty Trash service to clear this directory on a periodic basis.

When you create a new service you can configure it to apply to all repositories, the repositories in a Nexus Group, or a specific Nexus Repository. A service can be scheduled to run once at a specific date and time, or periodically once every Day, Week, or Month. If none of these options suit your specific needs, you can select a recurrence of "Advanced" which will allow you to supply your own cron expression to specify when the job should execute. To create a new scheduled task, click on Scheduled Tasks under the Administration menu, and click on the Add button. This will bring up the screen shown in <xref linkend="fig-repomap-scheduled" />.

Managing Nexus Scheduled Tasks

figs/web/repository-manager_schedule-service.png <imageobject

Managing Configuration Backups with a Scheduled Task

Nexus Professional includes a scheduled task which allows you to create automated, scheduled backups of your Nexus configuration. This scheduled job will archive the contents of the sonatype-work/nexus/conf directory. <xref linkend="fig-configuring-schedule-conf-backup" /> shows a scheduled configuration backup job configured to backup the contents of the Nexus configuration every day at 12:15 AM.

figs/web/configuring_schedule-conf-backup.png
Figure 56. Configuring a Scheduled Backup of Nexus Configuration

Once a backup has been run, the contents of the backup will be available in <filename>sonatype-work/nexus/backup in a series of ZIP archives which include the date and a timestamp.

Managing Security

Nexus has role-based access control (RBAC) which gives administrators very fine-grained control over who can read from a repository (or a subset of repositories), who can administer the server, and who can deploy to repositories. The security model in Nexus is also so flexible as to allow you to specify that only certain users or roles can deploy and manage artifacts in a specific repository under a specific groupId or asset class. The default configuration of Nexus ships with four roles and four users with a standard set of permissions that will make sense for most users. As your security requirements evolve, you’ll likely need to customize security settings to create protected repositories for multiple departments, or development groups. Nexus provides a security model which can adapt to any scenario. Nexus' Role-based access control (RBAC) system is designed around the following four security concepts:

Privileges

Privileges are rights to read, update, create, or manage resources and perform operations. Nexus ships with a set of core privileges which cannot be modified, and you can create new privileges to allow for fine-grained targeting of role and user permissions for specific repositories.

Targets

Privileges are usually associated with resources or targets. In the case of Nexus, a target can be a specific repository or a set of repositories grouped in something called a repository target. A target can also be a subset of a repository or a specific asset classes within a repository. Using a target you can apply to a specific privilege to apply to a single groupId.

Roles

Collections of privileges can be grouped into roles to make it easier to define collections of privileges common to certain classes of users. For example, deployment users will all have similar sets of permissions. Instead of assigning individual privileges to individual users, you use Roles to make it easier to manage users with similar sets of privileges. A role has one or more privilege and/or one or more roles.

Users

Users can be assigned roles and privileges, and model the individuals who will be logging into Nexus and read, deploying, or managing repositories.

Managing Privileges

Nexus has three types of privileges: application privileges which cover actions a user can execute in Nexus, repository target privileges which govern the level of access a user has to a particular repository or repository target, and repository view privileges which control whether a user can view a repository. Behind the scenes, a privilege is related to a single REST operation and method like create, update, delete, read.

figs/web/repository-manager_security-privileges.png
Figure 57. Managing Security Privileges

To create a new privilege, click on the Add… button in the Privileges panel and choose Repository Target privilege. Creating a privilege will load the New Repository Target Privilege form shown in <xref linkend="fig-configuring-new-privilege" />. This form takes a privilege name, a privilege description, the repository to target, and a repository target.

figs/web/repository-manager_security-privileges-2.png
Figure 58. Managing Security Privileges

Once you create a new privilege, it will create four underlying privileges: create, delete, read, and update. The four privileges created by the form in <xref linkend="fig-configuring-new-privilege" /> are shown in <xref linkend="fig-configuring-new-privileges" />.

figs/web/repository-manager_security-privileges-3.png
Figure 59. Create, Delete, Read, and Update Privileges Created

Managing Repository Targets

A target is a set of regular expressions to match on a path (exactly how the route rules work now). This allows you to define for example a target called Apache Maven which is "org/apache/maven/.*" You can then add a new privilege that relates to the target and controls the CRUD operations for artifacts matching that path (the privilege can span multiple repositories if you want). You could thus delegate all control of org.apache.maven targets to a "Maven" team. In this way, you don’t need to create separate repositories for each logical division of your artifacts.

figs/web/repository-manager_repository-targets.png
Figure 60. Managing Repository Targets
figs/web/repository-manager_repository-targets-2.png
Figure 61. Managing Repository Targets

Managing Security Roles

Nexus ships with four roles: Nexus Administrator Role, Nexus Anonymous Role, Nexus Developer Role, and Nexus Deployment Role. Click on the Roles link under Security in the Nexus menu to show the list of roles shown in <xref linkend="fig-configuring-security-roles" />.

figs/web/repository-manager_security-roles.png
Figure 62. Managing Security Roles

To create a new role, click on the Add… button and fill out the New Nexus Role form shown in <xref linkend="fig-configuring-creating-new-role" />. When creating a new role, you will need to supply a role identifier, a role name, a description, and a session timeout. Roles are comprised of other roles and individual privileges, to assign a role or privilege to a role, click on the role or privilege under Available Roles/Privileges and drag the role or privilege to the Selected Roles/Privileges list.

figs/web/repository-manager_security-roles-3.png
Figure 63. Managing Security Roles

The built-in roles Nexus Administrator Role, Nexus Anonymous Role, Nexus Deployment Role, and Nexus Developer Role are managed by Nexus and cannot be edited or deleted. Selecting one of these built-in roles will load the form shown in <xref linkend="fig-configuring-builtin-role" />.

figs/web/repository-manager_security-roles-2.png
Figure 64. Managing Security Roles

A Nexus role is comprised of other Nexus roles and individual Nexus privileges. To view the component parts of a Nexus Role, select the role in the Roles panel and then choose the Role Tree tab as shown in <xref linkend="fig-configuring-role-tree" />.

figs/web/repository-manager_security-roles-4.png
Figure 65. Managing Security Roles

With the Repository Targets, you have fine grained control over every action in the system. For example you could make a target that includes everything except sources (.(?!-sources)\.) and assign that to one group while giving yet another group access to everything. This means you can host your public and private artifacts in a single repository without giving up control of your private artifacts.

Managing Users

Nexus ships with three users: admin, anonymous, and deployment. The admin user has all privileges, the anonymous user has read-only privileges, and the deployment user can both read and deploy to repositories. If you need to create users with a more focused set of permissions, you can click on Users under Security in the left-hand navigation menu. Once you see the list of users, you can click on a user to edit that specific user’s user ID, name, email, or status. You can also assign or revoke specific roles or permissions for a particular user.

figs/web/repository-manager_security-users.png
Figure 66. Managing Users

A user can be assigned one or more roles which in turn can include references to other Nexus roles or to individual Nexus privileges. To view a tree of assigned Nexus roles and privileges, select the Role Tree for a particular user as shown in <xref linkend="fig-configuring-security-user-role-tree" />.

figs/web/repository-manager_security-users-role-tree.png
Figure 67. Nexus User Role Tree

If you need to find out exactly how a particular user has been granted a particular privilege, you can use the Privilege Trace pane as shown in <xref linkend="fig-configuring-security-user-priv-trace" />. The Privilege Trace pane lists all of the privileges that have been granted to a particular user. Clicking on a privilege loads a tree of roles that grant that particular privilege to a user. If a user has been assigned a specific privilege by more than one Role or Privilege assignment, you will be able to see this reflected in the Role Containment list.

figs/web/repository-manager_security-users-privilege.png
Figure 68. Nexus User Privilege Trace

Network Configuration

By default, Nexus listens on port 8081. You can change this port, by changing the value in shown in <xref linkend="ex-plexus-props" />. To change the port, stop Nexus, change the value of applicationPort in this file, and then restart Nexus. Once you do this, you should see a log you that Nexus is listening on the altered port.

Contents of conf/plexus.properties
applicationPort=8081
runtime=\${basedir}/runtime
apps=\${runtime}/apps
work=\${runtime}/work
webapp=\${runtime}/apps/nexus/webapp
nexus.configuration=\${runtime}/apps/nexus/conf/nexus.xml

Nexus Logging Configuration

You can configure the format and level of logging from within the Nexus interface. To do this, click on Log Configuration under the Administration menu in the left-hand navigation menu. Clicking on this link will display the panel shown in <xref linkend="fig-configuring-log-config" />.

figs/web/repository-manager_log-config.png
Figure 69. The Log Configuration Panel

From this panel you can configure the following logging configuration properties:

Root Logger Level

This controls how verbose the Nexus logging will be. If set to DEBUG, Nexus will be very verbose printing all log messages include debugging statements. If set to ERROR, Nexus will be far less verbose only printing out a log statement if Nexus encounters an error.

File Appender Pattern

This field controls the format of each log line. This field’s format corresponds to the format expected by a Log4J PatternAppender. For more information about this format, refer to the Javadoc for Log4J’s PatternAppender.

The other configuration parameters: Root Logger Appenders and File Append Location, are not editable in this release of Sonatype Nexus.

Managing Nexus Plugins

Use the Nexus Plugin Console to list all installed Nexus plugins and browse REST services made available by installed Nexus Plugin. To open the Nexus Plugin Console, click on the Plugin Console link in the Administration section of the Nexus menu as shown in <xref linkend="fig-configuring_plugin-console-admin-menu" />.

figs/web/configuring_plugin-console-admin-menu.png
Figure 70. Administrative Menu Link for the Plugin Console

Once you open the Nexus Plugin Console, you will see a list of plugins installed in your Nexus installation. Clicking on a Nexus plugin in this list will display information about the plugin including: the plugin’s name, the plugin version, status, a description, SCM information about the plugin, and the URL of the plugin’s project web site.

figs/web/configuring_plugin-console.png
Figure 71. Nexus Plugin Console

Once you have selected a plugin from the list of installed plugin, you can browse the available REST interfaces by selecting the REST Services tab as shown in <xref linkend="fig-configuring_plugin-console-rest" />. Each plugin can contribute one or more REST services to Nexus.

figs/web/configuring_plugin-console-rest.png
Figure 72. Nexus Plugin Console Displaying REST endpoints for a Plugin